Skip to main content

List holidays

Introduction#

Retrieves a list public holidays and observances for countries, states and provinces.

Rate limiting and throttling#

We're here to support the speed of your business - there are no rate limits in place.

Usage#

To list available countries, you'll need to make a request to GET /holidays endpoint. You can alter received response by using filters

const axios = require('axios');
axios.get('https://api.getfestivo.com/v2/holidays', {
params: {
api_key: "XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX",
country: "US",
year: 2020
}
})
.then(function (response) {
// handle success
console.log(response)
})
.catch(function (error) {
// handle error
console.log(error)
})
.then(function () {
// always executed
})

Filters#

In GET query you are able to append more parameters. Some of them are required some of them are optional, but each of them alter received list of holidays a bit. Please make yourself comfortable with the list below before you start using our Public Holidays API.

ParameterRequiredDescriptionTypeExample
countryyesISO 3166-1 alpha-2 country code from Countries section.stringUS
yearyes4-digit yearint2020
monthno1 or 2 digit month identifier (MM or M)int06
dayno1 or 2 digit day identifier (DD or D)int23
languagenoISO 639-1 language code (default: en). Please be notified not all countries have their holiday names available in different languages.stringen
beforenoReturn only holidays before given date (default: 0)bool1
afternoReturn only holidays after given date (default: 0)bool1
betweennoReturn only holidays between dates (NOTE: for this option to work, please pass month, and day if desired, as array of values, months and days, e.g. &month=1&month=5 to get holidays between January and May)bool1
publicnoReturn only public holidaysbool1
formatnoDefine return data format (available: json, xml)stringjson
timezonenoConvert start and end date and time according to passed timezonestringEurope/London

Substitute holidays#

Depending on country, if a holiday falls on Sunday or Saturday, the holiday is legally moved to another day, usually first following working day, e.g. next Monday. This is something we call substitute holiday. Such thing happens quite often, and to save you the burden to remember about all those complicated regulations and rules that differ between country to country, we are automatically marking such holidays with substitute flag, as well as we're returning the actual date when the holiday takes place as holiday.observed property.

Please bear in mind that sometimes those rules are overly complicated and may even differ between cities or provinces of a country. In such event, we try to cover those cases, or we use the "general" rule (e.g. in Canada we may use federal-level rule over regional).

Languages#

In order to support your global operations and as a response to our growing worldwide customer base, we've introduced language support in late 2018. By passing language's ISO 639-1 code as language (or lang) parameter, you're altering the returned holiday name in holiday.name response property to your language-of-choice. List of all ISO 639-1 language codes is available here.

All languages available for specific country are listed under availableFilters.language property.

If we don't support the language you specified, we use standard English name as a fallback.

Timezones#

We care about you and your business and support your global operations. For this purpose, to ease you handling different holidays in different countries and timezones, we convert start and end dates of holidays according to timezone parameter, of course if you'll pass it.

We support all timezones in TZ database format.

Responses#

Possible HTTP response codes#

Response status codes are returned as both the HTTP status code and as part of the response body.

CodeDescription
200All okay
400Validation error. Please refer to errors array available in received response.
401Authorization error. Check your api_token parameter and if you have active subscription.
402Payment Required. Upgrade your subscription plan. More information can be found in the message parameter of the response.
403Authentication error. Requested resource/feature/filter is not available for you/in your plan, or you've exceeded your monthly requests allowance.
429You've exceeded rate limit available in your plan.
500Fatal error at our end. We should get reported automatically but contact us if it'll keep occurring.

Response properties#

CodeTypeDescription
statusintStatus code for the response.
queryobjectObject containing passed query details
requestIdstringUnique identifier of the request. Include this as reference when reporting issues.
holidays.idstringUnique identifier for the holiday.
holidays.namestringName of the holiday or observance. Format: YYYY-MM-DD
holidays.datedateDate that the holiday actually occurs. Format: YYYY-MM-DD
holidays.observeddateDate that the holiday is observed on. Example, some countries move holidays that land on a weekend to the following Monday. Often times, this value may be the same as date.
holidays.substituteboolSubstitute holiday is another working day off work that is designated to replace a public holiday.
holidays.startdatetimeStart date and time in specified timezone of the holiday. Alterable by timezone parameter. Format: YYYY-MM-DD HH:ii:ss
holidays.enddatetimeEnd date and time in specified timezone of the holiday. Alterable by timezone parameter. Format: YYYY-MM-DD HH:ii:ss
holidays.typestringSpecific holiday type that this holiday has been recognised as.
holidays.publicboolWhether or not the holiday or observance is a public holiday.
holidays.countrystringISO 3166-1 alpha-2 code for the country that the holiday is for.
holidays.subdivisionsarrayTable containing ISO 3166-2 codes for states or provinces that the holiday is for.
availableFilters.languagearrayTable containing 639-1 codes for supported holiday name translations.

Example responses#

Standard request response#

Below is an example status 200 standard response returned by our API:

{
"holidays": [
{
"id": "20200101_7b8288babc5dd6fa3dd6520884b3ae9c",
"name": "New Year's Day",
"date": "2020-01-01",
"observed": "2020-01-01",
"substitute": false,
"start": "2020-01-01T00:00:00Z",
"end": "2020-01-01T23:59:59Z",
"type": "public",
"public": false,
"country": "US",
"subdivisions": []
},
{
"id: "20200104_57b934051701087f56f65a304638b6b7",
"name": "World Braille Day",
"date": "2020-01-04",
"observed": "2020-01-04",
"substitute": false,
"start": "2020-01-04T00:00:00Z",
"end": "2020-01-04T23:59:59Z",
"type": "observance",
"public": false,
"country": "US",
"subdivisions": []
},
...
]
}

Request using day parameter response#

Below is an example status 200 response returned by our API to a single day request:

{
"holidays": [
{
"id": "20200101_7b8288babc5dd6fa3dd6520884b3ae9c",
"name": "New Year's Day",
"date": "2020-01-01",
"observed": "2020-01-01",
"substitute": false,
"start": "2020-01-01T00:00:00Z",
"end": "2020-01-01T23:59:59Z",
"type": "public",
"public": false,
"country": "US",
"subdivisions": []
}
]
}