Public Holidays JSON: Format, Fields and How to Use It

Published 23-10-20263 min read

A public holidays API returns a JSON object with a list of holidays, where each holiday has a name, a date, a flag that says whether it is a public holiday, and the country it belongs to. This page explains the response of the HolidaysMap API field by field and shows how to read it safely.

Example response

{
  "count": 1,
  "holidays": [
    {
      "name": "New Year's Day",
      "date": "01-01-2024",
      "is_public": true,
      "country": "France",
      "country_code": "FR"
    }
  ]
}

Field reference

Field	Type	Meaning
holidays	array	The holidays that match your request. Empty when none match.
holidays[].name	string	The holiday name in English, for example New Year's Day.
holidays[].date	string	The date, written in the format you asked for with format.
holidays[].is_public	boolean	true when the day is a public holiday in that country.
holidays[].country	string	The country name.
holidays[].country_code	string	The country code, for example FR.

Always use is_public to decide whether a day is a public holiday. Do not assume that every entry in the list is one.

Choosing the date format

The format parameter controls how dates are read in your request and written in the response. The default is DD-MM-YYYY. The options are DD-MM-YYYY, YYYY-MM-DD, YYYY-DD-MM, MM-DD-YYYY, MM-YYYY-DD and DD-YYYY-MM. Every holiday in a response uses the same format.

Prefer YYYY-MM-DD. It is the ISO 8601 calendar date, it sorts correctly as text, and Date in JavaScript and date.fromisoformat in Python both read it directly.

JSON, CSV or XML

Add output=json, output=csv or output=xml to choose the response type. JSON is the default and the right choice for applications. CSV is convenient for spreadsheets and quick imports.

curl "https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&code=FR&date=2024-01-01&format=YYYY-MM-DD&output=csv"

Parse the response in JavaScript

const params = new URLSearchParams({
  key: process.env.HOLIDAYS_API_KEY,
  code: 'FR',
  date: '2024-01-01',
  format: 'YYYY-MM-DD',
});

const response = await fetch(`https://holidaysmap.com/api/v1/holidays?${params}`);
if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const { holidays } = await response.json();
const publicHolidays = holidays.filter((holiday) => holiday.is_public);
console.log(publicHolidays.map((holiday) => `${holiday.date}: ${holiday.name}`));

Parse the response in Python

import os

import requests

response = requests.get(
    "https://holidaysmap.com/api/v1/holidays",
    params={
        "key": os.environ["HOLIDAYS_API_KEY"],
        "code": "FR",
        "date": "2024-01-01",
        "format": "YYYY-MM-DD",
    },
    timeout=10,
)
response.raise_for_status()

for holiday in response.json()["holidays"]:
    if holiday["is_public"]:
        print(f'{holiday["date"]}: {holiday["name"]}')

Handling an empty result

A date that is not a holiday returns an empty holidays array, which is not an error. Treat a non-2xx status as a failure and an empty array as “regular day”. If requests start failing, check the API status page.

Next steps

See how to check whether a date is a public holiday, learn to calculate business days excluding public holidays, or look up a country code on the supported countries page.