HOLIDAY CALENDAR // API REFERENCE
Developer
Documentation
The primary reference for real-time global holiday data. Used by enterprise HR teams, e-commerce brands, and government organizations across 200+ countries.
Used by
ENDPOINT // GET
List Holidays
PublicReturns a paginated list of upcoming holidays. Supports query parameters for filtering by month, tag, and geographical region.
QUERY PARAMETERS
Number of results to return per page. Default is 20.
The current 1-indexed page of paginated results to fetch.
Search holidays by name or alternative name.
Filter by country using a country id from the /api/countries endpoint.
Return only holidays on or after this date. Format: YYYY-MM-DD. Use the current year (e.g. 2026-02-01).
Return only holidays on or before this date. Format: YYYY-MM-DD. Use the current year (e.g. 2026-02-28).
Filter by month number (1–12). January = 1, December = 12.
Filter by duration type. Options: Day, Week, Month.
Filter by category using a category id or slug from the /api/categories endpoint (e.g., recyMkFRxYQoCWBUv).
Filter by subcategory using a subcategory id or slug from
the /api/tags endpoint (e.g., recIemXy8TBhuC0oE).
Filter by the type of origin.
City Proclamation Community Origin Corporate Initiative Enacted Law Family Initiative Historical Origin Individual Initiative Institutional Initiative Legislative Resolution Religious Origin RETURNS
A list of holiday objects matching the query parameters. Each item contains the same full schema as the single holiday endpoint.
Unique database identifier for the holiday.
The absolute URL directly to the holiday's page on holidaycalendar.io.
The official name of the holiday.
Other common names or aliases for this holiday.
A short, descriptive summary of the holiday.
The duration type of the holiday (e.g., "Day", "Week", "Month").
The ISO date format when the holiday begins.
The ISO date format when the holiday ends.
Human-readable recurrence rule for when this holiday falls each year (e.g. "Second Monday in February").
Nested object containing month details.
Unique database identifier for the month.
The full name of the month (e.g., "February").
Nested object including country details.
Unique database identifier for the country.
The official name of the country.
The two-letter ISO country code.
Nested object including primary category details.
Unique database identifier for the category.
The full display name of the category.
A shortened presentation label for the category.
Nested object containing the primary subcategory for this holiday.
Unique database identifier for the subcategory.
The full display name of the subcategory.
A shortened presentation label for the subcategory.
Nested object containing details about the holiday's origin.
The category or nature of the holiday's origin.
Historical background and narrative regarding the holiday's founding.
Timestamp of when this holiday record was last updated.
The total number of holidays matching your query across all pages.
The current page number of the paginated query.
The max number of items returned per page.
Calculated total available pages for the current query parameters.
curl -X GET "https://api.holidaycalendar.io/api/holidays" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"{
"success": true,
"data": {
"items": [
{
"id": "recaRHklYIO3nt1AK",
"url": "https://www.holidaycalendar.io/holiday/national-poop-day",
"name": "National Poop Day",
"alternativeNames": "Poop Day",
"excerpt": "A health observance on February 9 to encourage discussion of digestion, bowel habits, and sanitation.",
"type": "Day",
"startDate": "2026-02-09",
"endDate": "2026-02-09",
"datePattern": "Second Monday in February",
"month": {
"id": "rec6dQgzms5EYZBau",
"name": "February"
},
"country": {
"id": "recYxvMVBeTBnsPrJ",
"name": "United States",
"code": "US"
},
"category": {
"id": "recyMkFRxYQoCWBUv",
"name": "Health & Wellness",
"label": "Health"
},
"subCategory": {
"id": "recIemXy8TBhuC0oE",
"name": "General Wellness & Healthy Habits",
"label": "General Wellness"
},
"origin": {
"type": "Institutional Initiative",
"text": "In 2016, Madison Children's Museum ran a youth \"Polling Place\" election that passed a referendum to celebrate Poop Day."
},
"lastUpdated": "2026-02-22T01:27:27Z"
},
{
"id": "recH2ysbwLKGGFnDf",
"url": "https://www.holidaycalendar.io/holiday/2a-day",
"name": "2A Day",
"alternativeNames": "Second Amendment Day",
"excerpt": "Informal observance on April 17 to highlight the Second Amendment and advocate for the right of United States citizens to keep and bear arms.",
"type": "Day",
"startDate": "2026-04-17",
"endDate": "2026-04-17",
"datePattern": "April 17",
"month": {
"id": "rec33akjU89SNU3zP",
"name": "April"
},
"country": {
"id": "recYxvMVBeTBnsPrJ",
"name": "United States",
"code": "US"
},
"category": {
"id": "rec7qY7zmXDW8Msre",
"name": "Cultural Heritage",
"label": "Culture"
},
"subCategory": {
"id": "recIemXy8TBhuC0oE",
"name": "History & Civics",
"label": "Civics"
},
"origin": {
"type": "Civic Advocacy",
"text": "An informal observance founded by Second Amendment advocates to promote awareness of constitutional rights."
},
"lastUpdated": "2026-02-22T01:27:27Z"
}
],
"total": 5906,
"page": 1,
"limit": 100,
"totalPages": 59
}
}ENDPOINT // GET
Get Single Holiday
PublicRetrieves the metadata schema for a specific individual holiday, including its core attributes and historical origin details.
PATH PARAMETERS
The unique database identifier (ID) of the holiday (e.g., recaRHklYIO3nt1AK).
RETURNS
Unique database identifier for the holiday.
The absolute URL directly to the holiday's page on holidaycalendar.io.
The official name of the holiday.
Other common names or aliases for this holiday.
A short, descriptive summary of the holiday.
The duration type of the holiday (e.g., "Day", "Week", "Month").
The ISO date format when the holiday begins.
The ISO date format when the holiday ends.
Human-readable recurrence rule for when this holiday falls each year (e.g. "Second Monday in February").
Nested object containing month details.
Unique database identifier for the month.
The full name of the month (e.g., "February").
Nested object containing country assignment and ISO code.
Unique database identifier for the country.
The official name of the country.
The two-letter ISO country code.
Nested object containing primary category details.
Unique database identifier for the category.
The full display name of the category.
A shortened presentation label for the category.
Primary subcategory for this holiday.
Unique database identifier for the subcategory.
The full display name of the subcategory.
A shortened presentation label for the subcategory.
Nested object containing details about the holiday's origin.
The category or nature of the holiday's origin.
Historical background and narrative regarding the holiday's founding.
Timestamp of when this holiday record was last updated.
curl -X GET "https://api.holidaycalendar.io/api/holidays/recaRHklYIO3nt1AK" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"{
"success": true,
"data": {
"id": "recaRHklYIO3nt1AK",
"url": "https://www.holidaycalendar.io/holiday/national-poop-day",
"name": "National Poop Day",
"alternativeNames": "Poop Day",
"excerpt": "A health observance on February 9 to encourage discussion of digestion, bowel habits, and sanitation.",
"type": "Day",
"startDate": "2026-02-09",
"endDate": "2026-02-09",
"datePattern": "Second Monday in February",
"month": {
"id": "rec6dQgzms5EYZBau",
"name": "February"
},
"country": {
"id": "recYxvMVBeTBnsPrJ",
"name": "United States",
"code": "US"
},
"category": {
"id": "recyMkFRxYQoCWBUv",
"name": "Health & Wellness",
"label": "Health"
},
"subCategory": {
"id": "recIemXy8TBhuC0oE",
"name": "General Wellness & Healthy Habits",
"label": "General Wellness"
},
"origin": {
"type": "Institutional Initiative",
"text": "In 2016, Madison Children’s Museum ran a youth “Polling Place” election that included a referendum on whether the museum should celebrate Poop Day. The referendum passed and the museum incorporated the observance into its calendar."
},
"lastUpdated": "2026-02-22T01:27:27Z"
}
}ENDPOINT // GET
List Countries
PublicRetrieves all supported countries used in geographical routing and filtering, alongside total holiday volume.
RETURNS
An array containing the requested countries.
Unique database identifier for the country.
Two-letter ISO country code.
The full English display name of the country.
The total volume of active holidays within this country.
The total number of countries returned in the request.
curl -X GET "https://api.holidaycalendar.io/api/countries" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"{
"success": true,
"data": [
{
"id": "recjKsu8XMgl3dbjP",
"code": "US",
"name": "United States",
"holidayCount": 482
},
{
"id": "recnRW9ijfD4rRAM2",
"code": "GB",
"name": "United Kingdom",
"holidayCount": 315
},
{
"id": "recus3cZpaupVUvgS",
"code": "JP",
"name": "Japan",
"holidayCount": 189
}
],
"count": 195
}ENDPOINT // GET
List Categories
PublicRetrieves all active holiday categories, complete with slugs and the total volume of holidays inside each category bucket.
RETURNS
An array containing the requested categories.
Unique database identifier for the category.
The full display name of the category.
A shortened presentation label suitable for UI pill components.
The total number of active holidays associated with this category.
Array of tags (subcategories) belonging to this category.
Unique database identifier for the subcategory.
The full display name of the subcategory.
Shortened UI label for the subcategory.
Total number of active holidays in this subcategory.
The total number of categories returned in the request.
curl -X GET "https://api.holidaycalendar.io/api/categories" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"{
"success": true,
"data": [
{
"id": "recjKsu8XMgl3dbjP",
"name": "Animals & Pets",
"label": "Animals",
"holidayCount": 53,
"subCategories": [
{
"id": "recnRW9ijfD4rRAM2",
"name": "Wildlife",
"label": "Wildlife",
"holidayCount": 31
},
{
"id": "recus3cZpaupVUvgS",
"name": "Small Pets",
"label": "Small Pets",
"holidayCount": 22
}
]
},
{
"id": "recj3bh3I3bvoaP7l",
"name": "Awareness & Advocacy",
"label": "Awareness",
"holidayCount": 112,
"subCategories": [
{
"id": "recbS3v6l59tBPcJH",
"name": "Social Justice & Civil Rights",
"label": "Social Justice",
"holidayCount": 85
}
]
}
],
"count": 22
}ENDPOINT // GET
List Sub Categories
PublicRetrieves all granular subcategories within the system. This endpoint returns the full unpaginated list of all active subcategories.
RETURNS
An array containing the requested subcategories.
Unique database identifier for the subcategory.
The full descriptive name of the subcategory.
A shortened presentation label suitable for UI pill components.
The total number of active holidays associated with this subcategory.
Object containing the parent category details.
Unique database identifier for the parent category.
The full display name of the parent category.
The total number of subcategories returned in the request.
curl -X GET "https://api.holidaycalendar.io/api/tags" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"{
"success": true,
"data": [
{
"id": "recOQ8a4Q3uXxU5x5",
"name": "Action & Adventure",
"label": "Action",
"holidayCount": 24,
"parentCategory": {
"id": "recVOV1o4VdHd1HXm",
"name": "Entertainment"
}
},
{
"id": "recIHcXgGkSp1JEAk",
"name": "Academic Milestones",
"label": "Academic",
"holidayCount": 12,
"parentCategory": {
"id": "recW6phcepbVAEaW7",
"name": "Education & Learning"
}
},
{
"id": "recdeotMCKS8QtNmy",
"name": "Accessories & Jewelry",
"label": "Accessories",
"holidayCount": 7,
"parentCategory": {
"id": "recV1CJA9aE6KvuKz",
"name": "Fashion & Beauty"
}
}
],
"count": 147
}