We have updated our API to version 2.0 to support all countries, states and regions with increaseddata points. Please update your API calls to v2. V1 of the API has been deprecated. Contactinfo@calendarific.com with any questions.
Welcome to the Calendarific Global Holidays API. We cover over 230 countries and 3000 states aroundtheworld. We are constantly adding new countries and states. Feel free to send us an email if yourcountry is not included in the list. This document covers how to use our API. Let us know if youhaveany questions.
The Calendarific API is built on REST principles. Authenticated users can interact with any of ourURIs by using the specified HTTP request method. We enforce using SSL encryption by issuing requeststhrough HTTPS.
API Base URL
All requests to our API are supposed to be sent to this endpoint. Below you will find a list ofendpoints 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 theseendpoints count towards your API hits quota. If you are on the free plan it will count towards yourallotments.
/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 allholidaysare specified in the language listed. If a holiday is not available in the specifiedlanguage, it defaults to the official language of the country or english in most cases.Thisis 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 usefulforgetting 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 authenticateyouwith our API, and it should be provided as aapi_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, theyear 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 beprocessed.
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 onlyrequired 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 andfuture 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 replacethe 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 getsreturned. Please note that some of the optional parameters are only limited to paid users. Belowis the complete list of optional parameters
day | Limits the number of holidays to a particular day. Must be passed as the numeric valueof the day [1..31]. |
month | Limits the number of holidays to a particular month. Must be passed as the numericvalue 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 orregion. The value of field is iso-3166 format of the state. View a list ofsupported countries and states. An example is, forNew York state in the United States, it would be us-ny |
type | We support multiple types of holidays and observances. This parameter allows users toreturn only a particular type of holiday or event. By default, the API returns allholidays. Below is the list of holiday types supported by the API and this is how toreference them.
|
Premium Holiday API Endpoint Parameters
Our API supports premium parameters which are available to all users of our professional planand above. You will receive an error if you use these parameters without the requiredsubscription.
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-letterISO639 Language Code. An example is to return all the names of france holidaysin french you can just add the parameter like this: &language=fr |
uuid | Returns a UUID for every holiday returned in the response [true orfalse]. |
HTTP response codes
Every API request returns an appropriate HTTP response code and below is a list of what theymeanwith 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, thiscouldbe malformed JSON or incorrect fields. In this case, the response body contains JSONwith 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 yourrequest. In most cases the message is lost during the process, and we are notified so thatwe can investigate the issue. |
503 | Service Unavailable During planned service outages, Calendarific API services willreturn 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 statuscodealong 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, andsendback the appropriate JSON response rather than HTML. We do this based on the user agent forknown popular programming languages, tools and frameworks. There are a couple of other waystoforce a JSON response from us in the cases that it doesn't happen automatically though. Oneisto 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 requestsina 24 hour period we'll return a 429 HTTP status code to you. Paid plans come with monthlylimits, and configurable alerts.
JSONP/CORS Requests
JSONP and CORS are supported, allowing you to use Calendarific entirely in client-side code.ForJSONP You just need to specify the callback parameter, eg.
https://calendarific.com/?callback=callback
Most javascript libraries willautomatically handle this for you though.
