Global Holiday API Documentation

Introduction

Welcome to the Calendarific Global Holidays API. We cover over 230 countries and 3,300 states and regions around the world, and we are constantly adding more. This document covers how to use the API — email us if your country is not included, or if you have any questions.

The API is built on REST principles: authenticated GET requests over HTTPS, JSON responses. Every endpoint lives under the same base URL and takes your API key as a query parameter.

API Base URL

All requests are sent to this base URL, followed by the endpoint path.

https://calendarific.com/api/v2

Authentication

An API key is required for every request. It authenticates you with the API and is passed as the api_key query parameter. Requests without a valid key return HTTP 401 with error_type: "auth failed".

Your key is shown on your account dashboard. If you do not have one yet, sign up for a free account. Keep the key private: anyone who has it can spend your quota, and you can rotate it from the dashboard at any time.

?api_key=YOUR_API_KEY

The api_key is appended to the request URL like in the example below.

curl -G "https://calendarific.com/api/v2/holidays" --data-urlencode "api_key=YOUR_API_KEY"

API Endpoints

Three endpoints cover holiday data and the country and language indexes. Every request to any of them counts towards your plan's quota.

Holidays Endpoint Parameters

Queries are made with URL parameters. api_key, country, and year are required on every /holidays request; requests missing any of them are rejected. The optional parameters filter the result and can be combined freely.

Required parameters

Example request

All holidays in the United States for 2026. Replace YOUR_API_KEY with the key from your account dashboard.

curl -G "https://calendarific.com/api/v2/holidays" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  -d "country=US" -d "year=2026"

const params = new URLSearchParams({ api_key: "YOUR_API_KEY", country: "US", year: 2026 });
const res = await fetch("https://calendarific.com/api/v2/holidays?" + params);
const data = await res.json();
console.log(data.response.holidays);

import requests

r = requests.get(
    "https://calendarific.com/api/v2/holidays",
    params={"api_key": "YOUR_API_KEY", "country": "US", "year": 2026},
)
print(r.json()["response"]["holidays"])

$query = http_build_query(['api_key' => 'YOUR_API_KEY', 'country' => 'US', 'year' => 2026]);
$data = json_decode(file_get_contents("https://calendarific.com/api/v2/holidays?" . $query), true);
print_r($data['response']['holidays']);

Example response

A shortened successful response. Every holiday carries its name and description, the country, the date as an ISO string and as year / month / day, the list of types it belongs to, its primary type, a canonical URL, and the locations it applies to (All, or the regions it is limited to).

{
    "meta": { "code": 200 },
    "response": {
        "holidays": [
            {
                "name": "Labor Day",
                "description": "Labor Day is a federal holiday in the United States. It gives workers a day of rest and celebrates their contribution to the American economy.",
                "country": { "id": "us", "name": "United States" },
                "date": {
                    "iso": "2026-09-07",
                    "datetime": { "year": 2026, "month": 9, "day": 7 }
                },
                "type": [ "National holiday" ],
                "primary_type": "Federal Holiday",
                "canonical_url": "https://calendarific.com/holiday/us/labor-day",
                "urlid": "us/labor-day",
                "locations": "All",
                "states": "All"
            }
        ]
    }
}

On the Business and Enterprise plans each holiday also carries an id and a stable uuid, so you can store and de-duplicate holidays across years and languages.

Optional Parameters

Optional parameters filter the results that come back. They can be combined — for example month=12&type=national returns the national holidays of December.

Plan Features

All plans use the same endpoints and parameters. Two things scale with the plan: how language is honoured, and the identifiers included in each holiday. The pricing page lists the monthly request limits.

HTTP Response Codes

Every request returns an HTTP status code and a JSON body. Successful requests return 200; every error response carries a machine-readable error_type — see error responses.

Error Responses

Error bodies keep the same shape as successful ones: meta carries the code, an error_type you can branch on, and a human-readable error_detail; response is empty.

{
    "meta": {
        "code": 429,
        "error_type": "rate_limit_exceeded",
        "error_detail": "Request limits exceeded. See https://calendarific.com/api-documentation for details or email the support team at info@calendarific.com"
    },
    "response": []
}

Response Format

Every endpoint returns JSON with a Content-Type of application/json, whether the request comes from a browser, a script, or the command line. Successful responses have meta.code 200 and the payload under response; error responses are described above. Dates are ISO 8601 (YYYY-MM-DD) and country and region codes are lower-case ISO 3166.

Rate Limits

The Free plan includes 500 requests per month; paid plans come with higher monthly limits — see plans and pricing. Every request to any endpoint counts, including requests that return an error. Once a limit is reached the API returns HTTP 429 with error_type: "rate_limit_exceeded" until the quota resets. Your current usage is shown on the account dashboard.

CORS

CORS is enabled on every endpoint (Access-Control-Allow-Origin: *), so the API can be called directly from browser code. Remember that anything in front-end code is public: if you call the API from a page anyone can visit, your API key — and your quota — are visible to them. For public sites, call the API from your server and cache the results. JSONP is not supported; use CORS.