Welcome to the Calendarific Global Holidays API. We cover over 200 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.

The Calendarific 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 URL

https://calendarific.com/api/v2

Authentication

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 account pages. If you do know your API key please signup for a free account key.

?api_key=baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs

The api_key should be appended to the url request like in the example below

 curl -G https://calendarific.com/api/v2/holidays?api_key=baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs

API Parameters

Queries are made to our API using URL parameters. There are two sets of parameters, optional and required. For the holidays API. The country, the year and api_key are required parameters for all holiday API requests. Requests that do not have the required parameter will recieve an error response and cannot be processed.

Required API Parameters

api_key This is the value of the API that is used to authenticate every request to our API. You can access this once you signup and login into your account.
country The country parameter must be in the iso-3166 format as specified in the document here. To view a list of countires and regions we support, visit our list of supported countries.
year The year you want to return the holidays. We currently support both historical and future years until 2049. The year must be specified as a number eg, 2019

Below is an example request for all holidays in the United States for 2019. Besure to replace the api_key with a valid value from your account page.

curl 'https://calendarific.com/api/v2/holidays?&api_key=baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs&country=US&year=2019'

Below is a shortened API response that executes successfully

{
    "meta": {
        "code": 200
    },
    "response": {
        "holidays": [
            {
                "name": "Name of holiday goes here",
                "description": "Description of holiday goes here",
                "date": {
                    "iso": "2018-12-31",
                    "datetime": {
                        "year": 2018,
                        "month": 12,
                        "day": 31
                    }
                },
                "type": [
                    "Type of Observance goes here"
                ]
            }
        ]
    }
}

Optional API Parameters

Our API has a list of optional parameters that allow users to refine the results that gets returned. Please note that some of the optional parameters are only limited to paid users. Below is the complete list of optional parameters

NB: Multiple types can be specified in the request seprated by commas.

day Limits the number of holidays to a particular day. Must be passed as the numeric value of the day [1..31].
month Limits the number of holidays to a particular month. Must be passed as the numeric value of the month [1..12].
location We support multiple counties, states and regions for all the countries we support. This optional parameter allows you to limit the holidays to a particular state or region. The value of field is iso-3166 format of the state. View a list of supported countries and states. An example is, for New York state in the United States, it would be us-ny
type We support multiple types of holidays and observances. This parameter allows users to return only a particluar type of holiday or event. By default, the API returns all holidays. Below is the list of holiday types supported by the API and this is how to reference them.
  • national - Returns public, federal and bank holidays
  • local - Returns local, regional and state holidays
  • religious - Return religious holidays: buddhism, christian, hinduism, muslim, etc
  • observance - Observance, Seasons, Times

HTTP response codes

Every API request returns an appropriate HTTP reponse code and below is a list of what they mean with regards to the API

200 Success Everything went smooth.
401 Unauthorized Missing or incorrect API token in header.
422 Unprocessable Entity meaning something with the message isn’t quite right, this could be malformed JSON or incorrect fields. In this case, the response body contains JSON with an API error code and message containing details on what went wrong.
500 Internal Server Error This is an issue with Calendarific's servers processing your request. In most cases the message is lost during the process, and we are notified so that we can investigate the issue.
503 Service Unavailable During planned service outages, Calendarific API services will return this HTTP response and associated JSON body.
429 Too many requests. API limits reached.

API error codes

Whenever the Calendarific server detects an input error it will return an HTTP 422 status code along with a JSON object containing error details:

600 Maintenance The Calendarific API is offline for maintenance.
601 Unauthorized Missing or incorrect API token.
602 Invalid query parameters.
603 Authorized Subscription level required.

JSON Response

We try to automatically detect when someone wants to call our API vs view our website, and send back the appropriate JSON response rather than HTML. We do this based on the user agent for known popular programming languages, tools and frameworks. There are a couple of other ways to force a JSON response from us in the cases that it doesn't happen automatically though. One is to add /json to the URL, and the other is to set an accepts header to application/json:

Rate Limits

Free usage of our API is limited to 1,000 API requests per day. If you exceed 1,000 requests in a 24 hour period we'll return a 429 HTTP status code to you. Paid plans come with monthly limits, and configurable alerts.

JSONP/CORS Requests

JSONP and CORS are supported, allowing you to use ipinfo.io entirely in client-side code. For JSONP You just need to specify the callback parameter, eg. https://calendarific.com/?callback=callback. Most javascript libraries will automatically handle this for you though.