Holiday List API Documentation
Access a global holiday database with our API, featuring public holidays, religious events, and national observances from year 1 to 2099. Easily integrate holiday data into your apps for scheduling, reminders and localization.
List Holidays
Retrieve detailed holiday information by country, province, date and year.
curl -G -d country="US" -d year="2024" -d key="YOUR_API_KEY" https://back.holidaylist.io/api/v1/holidaysRequired Parameters
country (string)
Country code in ISO 3166-1 format (e.g., US for the United States)
year (integer)
Year to filter holidays (e.g., 2024)
key (string)
Your API key
Optional
month (string)
Specify the month (1-12)
day (string)
Specify the day (1-31)
isPublic (boolean)
Filter public holidays only (true or false)
subdivisions (boolean)
Show holidays for subdivisions (true or false)
language (string)
Language code (e.g., "en", "fr")
search (string)
Holiday name
format (string)
Format (e.g., "json", "csv")
Return Properties
status (string)
Status code of the API request (e.g., 200 for success).
totalCount (integer)
Year to filter holidays (e.g., 2024)
country (string)
Your API key
year (string)
Your API key
data
An array with holiday information
data.name (string)
Name of the holiday or observance.
data.description (string)
Description of the holiday or observance.
data.date (date)
Date that the holiday actually occurs.
data.observed (date)
Date that the holiday is observed on. Example, some countries move holidays that land on a weekend to the following Monday. Often times, this value may be the same as date.
data.isPublic (boolean)
Whether or not the holiday or observance is a public holiday.
data.country (object)
Day of the week that the holiday occurs and is observed.
data.country.code (string)
A unique code representing the country
data.country.name (string)
The name of the country.
data.country.flag (string)
A string or URL representing the country’s flag
data.weekday (object)
Day of the week that the holiday occurs and is observed.
data.weekday.date.name (string)
Name of the day of the week that the holiday occurs. Corresponds with the date property.
data.weekday.date.numeric (number)
ISO-8601 numeric representation of the day of the week that the holiday occurs. Corresponds with the date property.
data.weekday.observed.name (string)
Name of the day of the week that the holiday is observed. Corresponds with the observed property.
data.weekday.observed.numeric (number)
ISO-8601 numeric representation of the day of the week that the holiday lands on. Corresponds with the date property.
Sample Holiday Response
{
"status": 200,
"totalCount": 1,
"country": "US",
"year": 2024,
"data": [
{
"name": "Holiday",
"description": "Holiday description",
"date": "28",
"observed": "28",
"isPublic": true,
"country": {
"code": "US",
"name": "United States",
"flag": "https://flagsapi.com/US/flat/64.png"
},
"weekday": {
"date": {
"name": "Monday",
"numeric": 1
},
"observed": {
"name": "Monday",
"numeric": 1
}
}
}
]
}List Countries
This endpoint retrieves a list of countries supported by the API. You can use the country codes from the response to query Holidays endpoint.
curl -X GET https://back.holidaylist.io/api/v1/countries?key=YOUR_API_KEYRequired Parameters
key (string)
Your API key
Optional
language (string)
Language code (e.g., "en", "fr")
page (number)
The page number to retrieve (useful for pagination)
pageSize (number)
Number of records per page
Return Properties
totalCount (number)
The total number of holidays returned by the API.
page (number)
The current page number
pageSize (number)
The number of countries returned per page
totalPages (number)
The total number of pages available
data
An array containing country objects
data.name (string)
The name of the country
data.code (string)
ISO country code (e.g. "US")
data.weekend (array)
Days of the week that are considered weekends (non-working days) in the country.
data.weekend.name (string)
Name of the day of the week that the weekend day occurs.
data.weekend.numeric (string)
ISO-8601 numeric representation of the day of the week that the weekend day occurs.
data.codes (object)
Not every system uses ISO 3166-1 alpha-2 codes. These codes provide an easy way to map ISO 3166-1 alpha 2 codes back to the codes your system uses.
data.codes.alpha_2 (string)
ISO 3166-1 alpha-2 code for the country.
data.codes.alpha_3 (string)
ISO 3166-1 alpha-2 code for the country.
data.codes.numeric (number)
ISO 3166-1 numeric code for the country.
data.languages (array)
Array of language objects
data.languages.code (string)
Language code
data.languages.name (string)
language name
data.currencies (array)
Currencies accepted as legal tender in the country.
data.currencies.alpha (string)
ISO 4217 alpha code for the currency.
data.currencies.name (number)
Name of currency
data.subdivisions (array)
Many countries are broken down into of smaller subdivisions. These subdivisions go by different names, like states or provinces and in some scenarios may represent countries or nations. For simplicity, we refer to these subdivisions collectively as States & Provinces.
data.subdivisions.code (string)
ISO 3166-2 code for the state / province. Use with /v1/holidays to request holidays for a specific state / province.
data.subdivisions.name (string)
Name of the state / province.
data.subdivisions.languages (array of strings)
Spoken languages for the state / province. Use with /v1/holidays to request holidays in a language other than English.
data.flag (string)
A URL pointing to the country’s flag
Sample Countries Response
{
"totalCount": 99,
"page": 1,
"pageSize": 20,
"totalPages": 5,
"data": [
{
"code": "US",
"name": "United States",
"weekend": [
{
"numeric": 1,
"name": "Sunday"
}
],
"codes": {
"alpha_2": "US",
"alpha_3": "USA",
"numeric": 840
},
"languages": [
{
"code": "en-us",
"name": "English"
}
],
"currencies": [
{
"alpha": "USD",
"name": "United States Dollar"
}
],
"flag": "https://flagsapi.com/US/flat/64.png",
"subdivisions": [
{
"code": "US-AK",
"name": "United States",
"languages": [
"en",
"es"
]
}
]
}
]
}List Languages
This endpoint retrieves a list of countries supported by the API. You can use the country codes from the response to query Holidays endpoint.
curl -X GET https://back.holidaylist.io/api/v1/languages?key=YOUR_API_KEYRequired Parameters
key (string)
Your API key
Optional
language (string)
Language code (e.g., "en", "fr")
page (number)
The page number to retrieve (useful for pagination)
pageSize (number)
Number of records per page
Return Properties
totalCount (number)
The total number of holidays returned by the API.
page (number)
The current page number
pageSize (number)
The number of countries returned per page
totalPages (number)
The total number of pages available
data
An array containing language objects
data.name (string)
Name of the country
data.code (string)
ISO country code (e.g., "US")
Sample Holiday Response
{
"totalCount": 12,
"page": 1,
"pageSize": 20,
"totalPages": 1,
"data": [
{
"code": "en",
"name": "English"
},
{
"code": "es",
"name": "Spanish"
}
]
}