Welcome to the Festivo. We cover 248 countries and states around the world. We are constantly adding new countries and states. Feel free to send us an email if your country is not included in the list. This document covers how to use our API. Let us know if you have any questions.
You can get started by using one of our SDKs in your project or making your own implementation. It cannot be simpler!
An API key is required for every request to the Festivo.
Your API key is used to authenticate you with our API, and it should be provided as a api_key URL parameter.
The API key can be retrieved from the dashboard page.
If you don't have an account yet, you can sign up for free!
Once you have your API Key, you should append it to your GET query, as per example:
$ curl -G
-d api_key="[ YOUR API KEY HERE]"
-d country="US"
-d year="2019"
"https://getfestivo.com/v1/holidays"
In other words, you need to make a simple GET request to https://getfestivo.com/v1/holidays, so in this case:
https://getfestivo.com/v1/holidays?api_key=[ YOUR API KEY HERE]&country=US&year=2019
Have a look at extra filters that may help you to get exactly the data you need.
The Festivo is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method. We enforce using SSL encryption by issuing requests through HTTPS.
Endpoint | Method | Authorization |
---|---|---|
/v1/holidays |
Get a list of all holiday information for a specific country. Alterable using Filters. | Yes |
Check out possible API Responses. Remember you are obligated to collect full responses in order to report bugs and issues.
Festivo follows standard HTTP response codes best practices in the industry. Each response comes with an appropriate response status code:
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. |
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. |
Below is an example status 200
standard response returned by our API:
{
"status": 200,
"envelope": {
"api_key": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX",
"remote_ip": "XXX.XXX.XXX.XXX",
"request_url": "https://getfestivo.com/v1/holidays?country=gb&year=2020&api_key=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX",
"signature": "95ce0e5f-7d86-45ee-a7b6-b2c63e61c7bf"
},
"requests": {
"used": 38,
"available": 72,
"resets": "2019-10-16T13:18:26.000Z"
},
"message": "",
"errors": null,
"holidays": {
"query": {
"country": "gb",
"year": "2019",
"api_key": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX"
},
"holidays": [
{
"date": "2020-01-01",
"start": "2020-01-01T00:00:00.000Z",
"end": "2020-01-02T00:00:00.000Z",
"name": "New Year's Day",
"type": "public",
"public": true,
"country": "GB"
},
{
"date": "2020-03-22",
"start": "2020-03-22T00:00:00.000Z",
"end": "2020-03-23T00:00:00.000Z",
"name": "Mother's Day",
"type": "observance",
"public": false,
"country": "GB"
},
...
{
"date": "2020-12-28",
"start": "2020-12-28T00:00:00.000Z",
"end": "2020-12-29T00:00:00.000Z",
"name": "Boxing Day (substitute day)",
"type": "public",
"substitute": true,
"public": true,
"country": "GB"
}
]
},
"availableFilters": {
"languages": [
"en"
],
"states": {
"ALD": "Alderney",
"ENG": "England",
"NIR": "Northern Ireland",
"SCT": "Scottland",
"WLS": "Wales"
}
}
}
Below is an example status 200
response returned by our API to a single day request:
{
"status": 200,
"message": "",
"errors": null,
"envelope": {
"api_key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"remote_ip": "127.0.0.1",
"request_url": "https://getfestivo.com/v1/holidays?api_key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&country=US&day=25&month=12&year=2017",
"signature": "d0a855a9cae7ef063b1b545fd98fb6ef"
},
"holidays": {
"holidays": [
{
"name": "Christmas",
"country": "US",
"date": "2017-12-25",
"public": null
}
]
}
}
Officially, are currently supporting 248 countries across all channels and constantly adding more. We have extra countries available on Alpha and Beta channel to our Enterprise customers.
Country | ISO 3166-1 alpha-2 code | Notes | |
---|---|---|---|
|
Afghanistan | AF | Beta Channel |
|
Albania | AL | -- |
|
Algeria | DZ | Beta Channel |
|
American Samoa | AS | -- |
|
Andorra | AD | -- |
|
Angola | AO | -- |
|
Anguilla | AI | -- |
|
Antarctica | AQ | Beta Channel |
|
Antigua And Barbuda | AG | -- |
|
Argentina | AR | -- |
|
Armenia | AM | -- |
|
Aruba | AW | -- |
|
Australia | AU | -- |
|
Austria | AT | -- |
|
Azerbaijan | AZ | -- |
|
Bahamas | BS | -- |
|
Bahrain | BH | -- |
|
Bangladesh | BD | -- |
|
Barbados | BB | -- |
|
Belarus | BY | -- |
|
Belgium | BE | -- |
|
Belize | BZ | -- |
|
Benin | BJ | -- |
|
Bermuda | BM | -- |
|
Bhutan | BT | Beta Channel |
|
Bolivia | BO | -- |
|
Bosnia And Herzegovina | BA | -- |
|
Botswana | BW | -- |
|
Bouvet Island | BV | Beta Channel |
|
Brazil | BR | -- |
|
British Indian Ocean Territory | IO | Beta Channel |
|
Brunei Darussalam | BN | -- |
|
Bulgaria | BG | -- |
|
Burkina Faso | BF | -- |
|
Burundi | BI | -- |
|
Cambodia | KH | Beta Channel |
|
Cameroon | CM | -- |
|
Canada | CA | -- |
|
Canary Islands | IC | Beta Channel |
|
Cape Verde | CV | -- |
|
Caribbean Netherlands | BQ | -- |
|
Cayman Islands | KY | Beta Channel |
|
Central African Republic | CF | -- |
|
Chad | TD | Beta Channel |
|
Chile | CL | -- |
|
China | CN | -- |
|
Christmas Island | CX | -- |
|
Cocos (keeling) Islands | CC | -- |
|
Colombia | CO | -- |
|
Comoros | KM | Beta Channel |
|
Congo | CG | -- |
|
Congo, The Democratic Republic Of The | CD | -- |
|
Cook Islands | CK | Beta Channel |
|
Costa Rica | CR | -- |
|
Cote D'ivoire | CI | Beta Channel |
|
Croatia | HR | -- |
|
Cuba | CU | -- |
|
Curaçao | CW | -- |
|
Cyprus | CY | -- |
|
Czech Republic | CZ | -- |
|
Denmark | DK | -- |
|
Djibouti | DJ | Beta Channel |
|
Dominica | DM | -- |
|
Dominican Republic | DO | -- |
|
Ecuador | EC | -- |
|
Egypt | EG | Beta Channel |
|
El Salvador | SV | -- |
|
Equatorial Guinea | GQ | -- |
|
Eritrea | ER | Beta Channel |
|
Estonia | EE | -- |
|
Ethiopia | ET | -- |
|
Falkland Islands (malvinas) | FK | Beta Channel |
|
Faroe Islands | FO | -- |
|
Fiji | FJ | Beta Channel |
|
Finland | FI | -- |
|
France | FR | -- |
|
French Guiana | GF | -- |
|
French Polynesia | PF | Beta Channel |
|
French Southern Territories | TF | Beta Channel |
|
Gabon | GA | -- |
|
Gambia | GM | Beta Channel |
|
Georgia | GE | Beta Channel |
|
Germany | DE | -- |
|
Ghana | GH | Beta Channel |
|
Gibraltar | GI | -- |
|
Greece | GR | -- |
|
Greenland | GL | -- |
|
Grenada | GD | -- |
|
Guadeloupe | GP | -- |
|
Guam | GU | -- |
|
Guatemala | GT | -- |
|
Guernsey | GG | -- |
|
Guinea | GN | Beta Channel |
|
Guinea-bissau | GW | Beta Channel |
|
Guyana | GY | -- |
|
Haiti | HT | -- |
|
Heard Island And Mcdonald Islands | HM | Beta Channel |
|
Honduras | HN | -- |
|
Hong Kong | HK | Beta Channel |
|
Hungary | HU | -- |
|
Iceland | IS | -- |
|
India | IN | Beta Channel |
|
Indonesia | ID | Beta Channel |
|
Iran, Islamic Republic Of | IR | Beta Channel |
|
Iraq | IQ | Beta Channel |
|
Ireland | IE | -- |
|
Isle of Man | IM | -- |
|
Israel | IL | Beta Channel |
|
Italy | IT | -- |
|
Jamaica | JM | -- |
|
Japan | JP | -- |
|
Jersey | JE | -- |
|
Jordan | JO | Beta Channel |
|
Kazakstan | KZ | Beta Channel |
|
Kenya | KE | -- |
|
Kiribati | KI | Beta Channel |
|
Korea, Democratic People's Republic Of | KP | Beta Channel |
|
Korea, Republic Of | KR | -- |
|
Kosovo | XK | -- |
|
Kuwait | KW | Beta Channel |
|
Kyrgyzstan | KG | Beta Channel |
|
Landskapet Åland | AX | -- |
|
Lao People's Democratic Republic | LA | Beta Channel |
|
Latvia | LV | -- |
|
Lebanon | LB | Beta Channel |
|
Lesotho | LS | -- |
|
Liberia | LR | Beta Channel |
|
Libyan Arab Jamahiriya | LY | Beta Channel |
|
Liechtenstein | LI | -- |
|
Lithuania | LT | -- |
|
Luxembourg | LU | -- |
|
Macau | MO | Beta Channel |
|
Macedonia, The Former Yugoslav Republic Of | MK | -- |
|
Madagascar | MG | -- |
|
Malawi | MW | -- |
|
Malaysia | MY | Beta Channel |
|
Maldives | MV | Beta Channel |
|
Malta | MT | -- |
|
Marshall Islands | MH | Beta Channel |
|
Martinique | MQ | -- |
|
Mauritania | MR | Beta Channel |
|
Mauritius | MU | Beta Channel |
|
Mayotte | YT | -- |
|
Mexico | MX | -- |
|
Micronesia, Federated States Of | FM | Beta Channel |
|
Moldova, Republic Of | MD | -- |
|
Monaco | MC | -- |
|
Mongolia | MN | Beta Channel |
|
Montenegro | ME | -- |
|
Montserrat | MS | Beta Channel |
|
Morocco | MA | Beta Channel |
|
Mozambique | MZ | -- |
|
Myanmar | MM | Beta Channel |
|
Namibia | NA | -- |
|
Nauru | NR | Beta Channel |
|
Nepal | NP | Beta Channel |
|
Netherlands | NL | -- |
|
New Caledonia | NC | Beta Channel |
|
New Zealand | NZ | -- |
|
Nicaragua | NI | -- |
|
Niger | NE | Beta Channel |
|
Nigeria | NG | Beta Channel |
|
Niue | NU | Beta Channel |
|
Norfolk Island | NF | Beta Channel |
|
Northern Mariana Islands | MP | Beta Channel |
|
Norway | NO | -- |
|
Oman | OM | Beta Channel |
|
Pakistan | PK | Beta Channel |
|
Palau | PW | Beta Channel |
|
Palestinian Territory, Occupied | PS | Beta Channel |
|
Panama | PA | -- |
|
Papua New Guinea | PG | Beta Channel |
|
Paraguay | PY | -- |
|
Peru | PE | -- |
|
Philippines | PH | -- |
|
Pitcairn | PN | Beta Channel |
|
Poland | PL | -- |
|
Portugal | PT | -- |
|
Puerto Rico | PR | Beta Channel |
|
Qatar | QA | Beta Channel |
|
Reunion | RE | -- |
|
Romania | RO | -- |
|
Russian Federation | RU | -- |
|
Rwanda | RW | -- |
|
Saint Helena | SH | -- |
|
Saint Kitts And Nevis | KN | Beta Channel |
|
Saint Lucia | LC | Beta Channel |
|
Saint Pierre And Miquelon | PM | Beta Channel |
|
Saint Vincent And The Grenadines | VC | Beta Channel |
|
Samoa | WS | Beta Channel |
|
San Marino | SM | -- |
|
Saudi Arabia | SA | Beta Channel |
|
Senegal | SN | Beta Channel |
|
Serbia | RS | -- |
|
Seychelles | SC | Beta Channel |
|
Sierra Leone | SL | Beta Channel |
|
Singapore | SG | -- |
|
Slovakia | SK | -- |
|
Slovenia | SI | -- |
|
Solomon Islands | SB | Beta Channel |
|
Somalia | SO | -- |
|
South Africa | ZA | -- |
|
South Georgia And The South Sandwich Islands | GS | Beta Channel |
|
South Sudan | SS | -- |
|
Spain | ES | -- |
|
Sri Lanka | LK | Beta Channel |
|
St. Barthélemy | BL | -- |
|
St. Martin | MF | Beta Channel |
|
Sudan | SD | Beta Channel |
|
Suriname | SR | Beta Channel |
|
Svalbard And Jan Mayen | SJ | -- |
|
Swaziland | SZ | Beta Channel |
|
Sweden | SE | -- |
|
Switzerland | CH | -- |
|
Syrian Arab Republic | SY | Beta Channel |
|
São Tomé and Príncipe | ST | Beta Channel |
|
Taiwan, Province Of China | TW | Beta Channel |
|
Tajikistan | TJ | Beta Channel |
|
Tanzania, United Republic Of | TZ | -- |
|
Thailand | TH | Beta Channel |
|
Togo | TG | -- |
|
Tokelau | TK | Beta Channel |
|
Tonga | TO | -- |
|
Trinidad And Tobago | TT | Beta Channel |
|
Tunisia | TN | Beta Channel |
|
Turkey | TR | -- |
|
Turkmenistan | TM | Beta Channel |
|
Turks And Caicos Islands | TC | Beta Channel |
|
Tuvalu | TV | Beta Channel |
|
Uganda | UG | -- |
|
Ukraine | UA | -- |
|
United Arab Emirates | AE | -- |
|
United Kingdom | GB | -- |
|
United States | US | -- |
|
United States Minor Outlying Islands | UM | Beta Channel |
|
Uruguay | UY | -- |
|
Uzbekistan | UZ | Beta Channel |
|
Vanuatu | VU | Beta Channel |
|
Vatican City | VA | -- |
|
Venezuela | VE | -- |
|
Viet Nam | VN | -- |
|
Virgin Islands, British | VG | Beta Channel |
|
Virgin Islands, U.s. | VI | Beta Channel |
|
Wallis And Futuna | WF | Beta Channel |
|
Western Sahara | EH | Beta Channel |
|
Yemen | YE | Beta Channel |
|
Zambia | ZM | -- |
|
Zimbabwe | ZW | -- |
If you would like to help adding your country's holidays to expand the service, please do not hesitate to contact us. To all collaborates we're offering a lifetime Premium Plan.
Following launch of Festivo v.1.1 we've extended returned data by field type that contains exact holiday type indicator (in opposition to public field which indicates only if given holiday is public or not)
Type | Description |
---|---|
public | public holiday |
bank | bank holiday, banks and offices are closed |
school | school holiday, schools are closed |
optional | majority of people take a day off |
observance | optional festivity, no paid day off |
Substitute holiday, compensate holiday or make up holiday refer to holidays created due to overlapping of some other holidays. In most of the cases, it happens because a holiday with a fixed date occur on weekends which is also holiday in most of the world.
At Festivo, in API response we're marking substitute holidays with a substitute
flag. Flag's value is always boolean and is always true.
Below an example of API response containing substitute holiday:
{
"status": 200,
"message": "",
"errors": null,
"envelope": {
"api_key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"remote_ip": "127.0.0.1",
"request_url": "https://getfestivo.com/v1/holidays?api_key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&country=GB&day=28&month=12&year=2020",
"signature": "d0a855a9cae7ef063b1b545fd98fb6ef"
},
"holidays": {
"holidays": [
{
"date": "2020-12-28",
"start": "2020-12-28T00:00:00.000Z",
"end": "2020-12-29T00:00:00.000Z",
"name": "Boxing Day (substitute day)",
"type": "public",
"substitute": true,
"public": true,
"country": "GB"
}
]
}
}
After Authentication' section api_key
parameter in your 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 API.
Parameter | Required? | Description | Format | Example |
---|---|---|---|---|
country |
Yes | ISO 3166-1 alpha-2 country code from Countries section. | string |
PL |
year |
Yes | 4-digit year | int |
2019 |
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: native). Check availableFilters in API response to see all available languages. |
string |
es |
previous |
No | Return only holidays before given date (default: 0) | bool |
1 |
upcoming |
No | Return only holidays after given date (default: 0) | bool |
1 |
public |
No | Return only public holidays | bool |
1 |
format |
No | Define return data format (available: json, xml) | string |
json |
pretty |
No | Output as human-readable text (default: 0) | bool |
0 |
state |
No | Filter holidays by country's state. Check availableFilters in API response to see all available states. |
string |
|
region |
No | Filter holidays by country's region | string |
|
type |
No | Filter holidays by type (public, bank, school, observance) | string |
Language/Framework | Download |
---|---|
PHP | https://github.com/SzymonDukla/HolidayAPI-Wrapper |
NodeJS | https://github.com/holidayapi-pl/node-holidayapi |
GO | https://github.com/holidayapi-pl/go-holidayapi |
Java | https://github.com/holidayapi-pl/java-holidayapi |
If you'd like to participate in development of new SDKs or you have already made a wrapper in your favourite language, please do let us know. We offer free Premium Plan subscription to authors of all verified SDKs.
We are here to assist you, thank you for report any bug/issue to our email [email protected].
What support includes?
What support doesn't include:
If you already read the documentation and you still need assistance, please send us an email to [email protected] or contact us via any other support channel available in your plan and we'll be glad to help you.