Chat with us, powered by LiveChat


Welcome to the Festivo. We cover over 120 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"


In other words, you need to make a simple GET request to, so in this case:

           [ 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.

Rate Limiting

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


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.

Standard request response

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

  "status": 200,
  "message": "",
  "errors": null,
  "envelope": {
    "remote_ip": "",
    "request_url": "",
    "signature": "2a371752bdc521f0743ea403dd880ef9"
  "holidays": {
    "holidays": {
      "2017-12-07": [
            "name": "Pearl Harbor Remembrance Day",
            "country": "US",
            "date": "2017-12-07",
            "public": null
      "2017-12-31": [
            "name": "New Year's Eve",
            "country": "US",
            "date": "2017-12-31",
            "public": null
            "name": "Sixth Day of Kwanzaa",
            "country": "US",
            "date": "2017-12-31",
            "public": null
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": {
        "remote_ip": "",
        "request_url": "",
        "signature": "d0a855a9cae7ef063b1b545fd98fb6ef"
      "holidays": {
        "holidays": [
            "name": "Christmas",
            "country": "US",
            "date": "2017-12-25",
            "public": null

Available Countries

Officially, are currently supporting 144 countries and constantly adding more. Another 70 countries are available to our chosen customers on a beta test basis.

Country ISO 3166-1 alpha-2 code
Albania AL
American Samoa AS
Andorra AD
Angola AO
Anguilla AI
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
Bolivia BO
Bosnia And Herzegovina BA
Botswana BW
Brazil BR
Brunei Darussalam BN
Bulgaria BG
Burkina Faso BF
Burundi BI
Cameroon CM
Canada CA
Cape Verde CV
Caribbean Netherlands BQ
Central African Republic CF
Chile CL
China CN
Christmas Island CX
Cocos (keeling) Islands CC
Colombia CO
Congo CG
Congo, The Democratic Republic Of The CD
Costa Rica CR
Croatia HR
Cuba CU
Curaçao CW
Cyprus CY
Czech Republic CZ
Denmark DK
Dominica DM
Dominican Republic DO
Ecuador EC
El Salvador SV
Equatorial Guinea GQ
Estonia EE
Ethiopia ET
Faroe Islands FO
Finland FI
France FR
French Guiana GF
Gabon GA
Germany DE
Gibraltar GI
Greece GR
Greenland GL
Grenada GD
Guadeloupe GP
Guam GU
Guatemala GT
Guernsey GG
Guyana GY
Haiti HT
Honduras HN
Hungary HU
Iceland IS
Ireland IE
Isle of Man IM
Italy IT
Jamaica JM
Japan JP
Jersey JE
Kenya KE
Korea, Republic Of KR
Kosovo XK
Landskapet Åland AX
Latvia LV
Lesotho LS
Liechtenstein LI
Lithuania LT
Luxembourg LU
Macedonia, The Former Yugoslav Republic Of MK
Madagascar MG
Malawi MW
Malta MT
Martinique MQ
Mayotte YT
Mexico MX
Moldova, Republic Of MD
Monaco MC
Montenegro ME
Mozambique MZ
Namibia NA
Netherlands NL
New Zealand NZ
Nicaragua NI
Norway NO
Panama PA
Paraguay PY
Peru PE
Philippines PH
Poland PL
Portugal PT
Reunion RE
Romania RO
Russian Federation RU
Rwanda RW
Saint Helena SH
San Marino SM
Serbia RS
Singapore SG
Slovakia SK
Slovenia SI
Somalia SO
South Africa ZA
South Sudan SS
Spain ES
St. Barthélemy BL
Svalbard And Jan Mayen SJ
Sweden SE
Switzerland CH
Tanzania, United Republic Of TZ
Togo TG
Tonga TO
Turkey TR
Uganda UG
Ukraine UA
United Arab Emirates AE
United Kingdom GB
United States US
Uruguay UY
Vatican City VA
Venezuela VE
Viet Nam VN
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


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


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?

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

What support doesn't include:

  1. Customization services
  2. 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.