Welcome to the Calendarific Global 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 signup for a free account key.

# With token query parameter

# Example request

API Parameters

Queries are made to our API using URL paramters. There are two sets of parameters, optional and required. For the holidays API. The country, the year and api_key are required paramters for all holiday API requests.

Required Parameters

  • country must be in the iso-3166 format as specified in the document here
  • year the year of the
  • api_key the year of the

Example request for holidays in NY in the US

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

Example Response

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

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 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. http://ipinfo.io/?callback=callback. Most javascript libraries will automatically handle this for you though. Here's a jQuery example that logs the client IP and country:


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://calendarific.com?api_key=XXXXXXX

Supported Countries

We currently have over a hundread countries, states and regions that we support. We are always adding details for all countries. To view a list of countires and regions we support, visit our list of supported countries.