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

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?

  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.