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.
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/holidays
Country code in ISO 3166-1 format (e.g., US for the United States)
Year to filter holidays (e.g., 2024)
Your API key
Specify the month (1-12)
Specify the day (1-31)
Filter public holidays only (true or false)
Show holidays for subdivisions (true or false)
Language code (e.g., "en", "fr")
Holiday name
Format (e.g., "json", "csv")
Status code of the API request (e.g., 200 for success).
Year to filter holidays (e.g., 2024)
Your API key
Your API key
An array with holiday information
Name of the holiday or observance.
Description of the holiday or observance.
Date that the holiday actually occurs.
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.
Whether or not the holiday or observance is a public holiday.
Day of the week that the holiday occurs and is observed.
A unique code representing the country
The name of the country.
A string or URL representing the country’s flag
Day of the week that the holiday occurs and is observed.
Name of the day of the week that the holiday occurs. Corresponds with the date property.
ISO-8601 numeric representation of the day of the week that the holiday occurs. Corresponds with the date property.
Name of the day of the week that the holiday is observed. Corresponds with the observed property.
ISO-8601 numeric representation of the day of the week that the holiday lands on. Corresponds with the date property.
{
"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
}
}
}
]
}
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_KEY
Your API key
Language code (e.g., "en", "fr")
The page number to retrieve (useful for pagination)
Number of records per page
The total number of holidays returned by the API.
The current page number
The number of countries returned per page
The total number of pages available
An array containing country objects
The name of the country
ISO country code (e.g. "US")
Days of the week that are considered weekends (non-working days) in the country.
Name of the day of the week that the weekend day occurs.
ISO-8601 numeric representation of the day of the week that the weekend day occurs.
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.
ISO 3166-1 alpha-2 code for the country.
ISO 3166-1 alpha-2 code for the country.
ISO 3166-1 numeric code for the country.
Array of language objects
Language code
language name
Currencies accepted as legal tender in the country.
ISO 4217 alpha code for the currency.
Name of currency
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.
ISO 3166-2 code for the state / province. Use with /v1/holidays to request holidays for a specific state / province.
Name of the state / province.
Spoken languages for the state / province. Use with /v1/holidays to request holidays in a language other than English.
A URL pointing to the country’s flag
{
"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"
]
}
]
}
]
}
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_KEY
Your API key
Language code (e.g., "en", "fr")
The page number to retrieve (useful for pagination)
Number of records per page
The total number of holidays returned by the API.
The current page number
The number of countries returned per page
The total number of pages available
An array containing language objects
Name of the country
ISO country code (e.g., "US")
{
"totalCount": 12,
"page": 1,
"pageSize": 20,
"totalPages": 1,
"data": [
{
"code": "en",
"name": "English"
},
{
"code": "es",
"name": "Spanish"
}
]
}