Holiday API Documentation

We have updated our API to version 2.0 to support all countries, states and regions with increased data points. Please update your API calls to v2. V1 of the API has been deprecated. Contact info@calendarific.com with any questions.

Welcome to the Calendarific Global Holidays API. We cover over 230 countries and 3000 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.

API Base URL

All requests to our API are supposed to be sent to this endpoint. Below you will find a list of endpoints that the API supports

https://calendarific.com/api/v2

API Endpoints

Below is a list of API endpoints we currently support. Please note that requests to any of these endpoints count towards your API hits quota. If you are on the free plan it will count towards your allotments.

`/holidays`	This provides a list of holidays based on the parameters passed to it.	`https://calendarific.com/api/v2/holidays`
`/languages`	This endpoint provides the list of languages we support. Please note that not all holidays are specified in the language listed. If a holiday is not available in the specified language, it defaults to the official language of the country or english in most cases. This is useful for getting an index of all languages and the ISO codes programmatically.	`https://calendarific.com/api/v2/languages`
`/countries`	This endpoint provides a list of countries and languages that we support. This is useful for getting an index of all countries and the ISO codes programmatically.	`https://calendarific.com/api/v2/countries`

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

Holiday API Endpoint 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 receive 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 sign up and login into your account. This is the only required parameter for the `/countries` endpoint.
`country`	The country parameter must be in the iso-3166 format as specified in the document here. To view a list of countries 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. Be sure 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 Holiday API Endpoint 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 separated 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 particular 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

Premium Holiday API Endpoint Parameters

Our API supports premium parameters which are available to all users of our professional plan and above. You will receive an error if you use these parameters without the required subscription.

`language`	Returns the name of the holiday in the official language of the country if available. This defaults to english. This must be passed as the 2-letter ISO639 Language Code. An example is to return all the names of france holidays in french you can just add the parameter like this: `&language=fr`
`uuid`	Returns a UUID for every holiday returned in the response [`true` or `false`].

HTTP response codes

Every API request returns an appropriate HTTP response 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`	Un-processable 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 Calendarific 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.

Global Holiday API Documentation