Documentation

Welcome to the Holiday API. 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!

API Key

An API key is required for every request to the Holiday API. 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://holidayapi.pl/v1/holidays"
                    
                

In other words, you need to make a simple GET request to https://holidayapi.pl/v1/holidays, so in this case:

                    
https://holidayapi.pl/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 Holiday API 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

Holiday API 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": {
    "api_key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "remote_ip": "127.0.0.1",
    "request_url": "https://holidayapi.pl/v1/holidays?api_key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&country=US&month=12&year=2017",
    "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": {
        "api_key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "remote_ip": "127.0.0.1",
        "request_url": "https://holidayapi.pl/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 88 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
Armenia AM
Aruba AW
Austria AT
Bahamas BS
Barbados BB
Belgium BE
Bolivia BO
Bosnia And Herzegovina BA
Botswana BW
Brazil BR
Canada CA
Cape Verde CV
Caribbean Netherlands BQ
Central African Republic CF
Chile CL
Congo CG
Costa Rica CR
Croatia HR
Cuba CU
Curaçao CW
Czech Republic CZ
Denmark DK
Dominica DM
Ecuador EC
El Salvador SV
Estonia EE
France FR
French Guiana GF
Germany DE
Greenland GL
Grenada GD
Guadeloupe GP
Guatemala GT
Guernsey GG
Haiti HT
Honduras HN
Hungary HU
Iceland IS
Indonesia ID
Ireland IE
Isle of Man IM
Italy IT
Jersey JE
Latvia LV
Lesotho LS
Liechtenstein LI
Lithuania LT
Luxembourg LU
Madagascar MG
Malta MT
Martinique MQ
Mayotte YT
Mexico MX
Netherlands NL
Nicaragua NI
Norway NO
Paraguay PY
Poland PL
Portugal PT
Reunion RE
Russian Federation RU
Rwanda RW
Saint Helena SH
San Marino SM
Sierra Leone SL
Slovakia SK
Slovenia SI
Somalia SO
South Sudan SS
Spain ES
St. Barthélemy BL
Sweden SE
Tanzania, United Republic Of TZ
Togo TG
Turkey TR
Uganda UG
United Kingdom GB
United States US
Vatican City VA
Venezuela VE
Viet Nam VN
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.

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

SDKs

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.