Welcome to the CalendarIndex Holiday API. We cover over 200 countries and states around the world and we are always adding new countries and states. Feel free to send us an email if your country is not included in the list. The document below covers how to use our API. Let us know if you any questions.
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 visit /login or signup for a free account key.
# With token query parameter ?api_key=XXXXXXX # Example request https://www.calendarindex.com/api/v1/holidays?api_key=XXXXXXX
Queries are made to our API using URL paramters. There are two sets of parameters, optional and required. For the holidays API. The
api_key are required paramters for all holiday API requests.
countrymust be in the iso-3166 format as specified in the document here
yearthe year of the
api_keythe year of the
statemust be in the iso-3166 format ad specified in this document
regionthe region where the request is coming in from
# Example request for holidays in NY in the US https://www.calendarindex.com/api/v1/holidays?country=US&year=2018&state=NY&api_key=XXXXXXX # Example 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:
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.
Our API is available over a secure HTTPS connection for all users, even on the free plan. Simply point add https:// to the requests to make the requests secure.
# Get details for your own IP address over HTTPS $ curl https://www.calendarindex.com?api_key=XXXXXXX