CalendarHoliday

Calendarholiday API Documentation

This documentation provides information on how to use the Holiday API. All endpoints require an API key passed in the header.

Note: Replace YOUR_API_KEY with your actual API key.

Holidays Endpoint

Retrieve a list of holidays.

URL

https://calendarholiday.com/api/holidays/

Headers

Header Value
Api-Key YOUR_API_KEY

Parameters

Name Description Required
country Filter by country code (ISO alpha-2). Yes
year Filter by year. Yes
date Filter by holiday date (YYYY-MM-DD). No
type Filter by holiday type (e.g., National). No
subdivision Filter by subdivision code (e.g., US-NY). No
is_observed Filter by observed holidays (true or false). No
is_estimated Filter by estimated holidays (true or false). No
is_half_day Filter by half-day holidays (true or false). No
is_bridge_holiday Filter by bridge holidays (true or false). No
search Search by holiday name or description. No
ordering Order results by specified fields (e.g., date, name). No

Example Request

curl -X GET \
  'https://calendarholiday.com/api/holidays/?country=US&year=2024' \
  -H 'Api-Key: YOUR_API_KEY'

Possible HTTP Responses

200 OK Successful retrieval of holiday list.
400 Bad Request Required Fields missing.
401 Unauthorized Missing or invalid API key.
403 Forbidden Access denied due to subscription plan restrictions.

Example JSON Response (HTTP 200)

[
    {
        "name": "New Year's Day",
        "date": "2025-01-01",
        "description": "Celebration of the New Year",
        "url": "https://calendarholiday.com/content/blog/everything-you-need-to-know-about-christmas/",
        "type": "National Holiday",
        "country": {
            "name": "Canada",
            "alpha2": "CA",
            "alpha3": "CAN",
            "numeric": "124",
            "weekend_days": "Sat,Sun"
        },
        "subdivisions": [],
        "is_observed": false,
        "is_estimated": false,
        "is_half_day": false,
        "is_bridge_holiday": false
    },
    // ... more holidays ...
}
]

Countries Endpoint

Retrieve a list of countries.

Endpoint

https://calendarholiday.com/api/countries/

Headers

Header Value
Api-Key YOUR_API_KEY

Parameters

Name Description Required
search Search by country name or code. No
ordering Order results by specified fields (name, alpha2). No

Example Request

curl -X GET \
  'https://yourdomain.com/api/countries/?search=Canada' \
  -H 'Api-Key: YOUR_API_KEY'

Possible HTTP Responses

200 OK Successful retrieval of country list.
400 Bad Request Required Fields missing.
401 Unauthorized Missing or invalid API key.
403 Forbidden Access denied due to subscription plan restrictions.

Example JSON Response (HTTP 200)

[
    {
        "name": "Australia",
        "alpha2": "AU",
        "alpha3": "AUS",
        "numeric": "036",
        "weekend_days": "Sat,Sun",
        "subdivisions": [
            {
                "name": "Queensland",
                "code": "AU-QLD"
            },
            {
                "name": "South Australia",
                "code": "AU-SA"
            },
            {
                "name": "Tasmania",
                "code": "AU-TAS"
            },
            {
                "name": "Australian Capital Territory",
                "code": "AU-ACT"
            },
            {
                "name": "Victoria",
                "code": "AU-VIC"
            },
            {
                "name": "New South Wales",
                "code": "AU-NSW"
            },
            {
                "name": "Western Australia",
                "code": "AU-WA"
            },
            {
                "name": "Northern Territory",
                "code": "AU-NT"
            }
        ]
    },
    // ... more countries ...
]