Documentation

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!

API Key

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!

Authentication

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="2020"

    "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=2020

Have a look at extra filters that may help you to get exactly the data you need.

Rate Limiting

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

Methods

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.

Responses

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.

Standard request response

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"
    }
  }
}

Request using day parameter response

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
          }
        ]
      }
    }

Available Countries

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.

Holiday Types

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 Holidays

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"
                }
        ]
      }
    }

Filters

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`

SDKs

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.

Support

We are here to assist you, thank you for report any bug/issue to our email [email protected].

What support includes?

Availability to answer questions
Answering technical questions about plan's features
Assistance with reported bugs and issues
Help with payments and subscription troubleshooting

What support doesn't include:

Customization services
Installation services

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.