List holidays
#
IntroductionRetrieves a list public holidays and observances for countries, states and provinces.
#
Rate limiting and throttlingWe're here to support the speed of your business - there are no rate limits in place.
#
UsageTo list available countries, you'll need to make a request to GET /holidays
endpoint.
You can alter received response by using filters
- JavaScript
- PHP
- Go
#
FiltersIn 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.
Parameter | Required | Description | Type | Example |
---|---|---|---|---|
country | yes | ISO 3166-1 alpha-2 country code from Countries section. | string | US |
year | yes | 4-digit year | int | 2020 |
month | no | 1 or 2 digit month identifier (MM or M) | int | 06 |
day | no | 1 or 2 digit day identifier (DD or D) | int | 23 |
language | no | ISO 639-1 language code (default: en). Please be notified not all countries have their holiday names available in different languages. | string | en |
before | no | Return only holidays before given date (default: 0) | bool | 1 |
after | no | Return only holidays after given date (default: 0) | bool | 1 |
between | no | Return 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) | bool | 1 |
public | no | Return only public holidays | bool | 1 |
format | no | Define return data format (available: json, xml) | string | json |
timezone | no | Convert start and end date and time according to passed timezone | string | Europe/London |
#
Substitute holidaysDepending 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).
#
LanguagesIn 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.
#
TimezonesWe 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 codesResponse status codes are returned as both the HTTP status code and as part of the response body.
Code | Description |
---|---|
200 | All okay |
400 | Validation error. Please refer to errors array available in received response. |
401 | Authorization error. Check your api_token parameter and if you have active subscription. |
402 | Payment Required. Upgrade your subscription plan. More information can be found in the message parameter of the response. |
403 | Authentication error. Requested resource/feature/filter is not available for you/in your plan, or you've exceeded your monthly requests allowance. |
429 | You've exceeded rate limit available in your plan. |
500 | Fatal error at our end. We should get reported automatically but contact us if it'll keep occurring. |
#
Response propertiesCode | Type | Description |
---|---|---|
status | int | Status code for the response. |
query | object | Object containing passed query details |
requestId | string | Unique identifier of the request. Include this as reference when reporting issues. |
holidays.id | string | Unique identifier for the holiday. |
holidays.name | string | Name of the holiday or observance. Format: YYYY-MM-DD |
holidays.date | date | Date that the holiday actually occurs. Format: YYYY-MM-DD |
holidays.observed | date | Date 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.substitute | bool | Substitute holiday is another working day off work that is designated to replace a public holiday. |
holidays.start | datetime | Start date and time in specified timezone of the holiday. Alterable by timezone parameter. Format: YYYY-MM-DD HH:ii:ss |
holidays.end | datetime | End date and time in specified timezone of the holiday. Alterable by timezone parameter. Format: YYYY-MM-DD HH:ii:ss |
holidays.type | string | Specific holiday type that this holiday has been recognised as. |
holidays.public | bool | Whether or not the holiday or observance is a public holiday. |
holidays.country | string | ISO 3166-1 alpha-2 code for the country that the holiday is for. |
holidays.subdivisions | array | Table containing ISO 3166-2 codes for states or provinces that the holiday is for. |
availableFilters.language | array | Table containing 639-1 codes for supported holiday name translations. |
#
Example responses#
Standard request responseBelow is an example status 200 standard response returned by our API:
#
Request using day parameter responseBelow is an example status 200 response returned by our API to a single day request: