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.

GET /api/v1/holidays
curl -G -d country="US" -d year="2024" -d key="YOUR_API_KEY" https://back.holidaylist.io/api/v1/holidays

Required 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

Arrow Down

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.

Arrow Down

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.

Arrow Down

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

Arrow Down
{
  "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.

GET /api/v1/countries
curl -X GET https://back.holidaylist.io/api/v1/countries?key=YOUR_API_KEY

Required 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

Arrow Down

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.

Arrow Down

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.

Arrow Down

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

Arrow Down

data.languages.code (string)

Language code

data.languages.name (string)

language name

data.currencies (array)

Currencies accepted as legal tender in the country.

Arrow Down

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.

Arrow Down

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

Arrow Down
{
  "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.

GET /api/v1/languages
curl -X GET https://back.holidaylist.io/api/v1/languages?key=YOUR_API_KEY

Required 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

Arrow Down

data.name (string)

Name of the country

data.code (string)

ISO country code (e.g., "US")

Sample Holiday Response

Arrow Down
{
  "totalCount": 12,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1,
  "data": [
    {
      "code": "en",
      "name": "English"
    },
    {
      "code": "es",
      "name": "Spanish"
    }
  ]
}