How to Check if a Date Is a Public Holiday with an API

Published 23-10-20263 min read

To check whether a date is a public holiday, send one request to a public holidays API with a country code and a date. If the response contains holidays, the date is a public holiday in that country; if it is empty, it is a regular day.

With the HolidaysMap API that is a single GET request to /api/v1/holidays.

What you need

• A free API key from your dashboard. Sign up on the free plan, no credit card required.
• A country code, for example RO for Romania or FR for France. The full list is on the supported countries page.
• The date you want to check. The default format is DD-MM-YYYY, and you can switch to YYYY-MM-DD with the format parameter.

Check a single date with cURL

curl "https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&code=FR&date=01-01-2024"

The response lists every holiday that falls on that date:

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

Check a date in JavaScript

async function isPublicHoliday(countryCode, isoDate) {
  const params = new URLSearchParams({
    key: process.env.HOLIDAYS_API_KEY,
    code: countryCode,
    date: isoDate,
    format: 'YYYY-MM-DD',
  });
  const response = await fetch(`https://holidaysmap.com/api/v1/holidays?${params}`);
  if (!response.ok) {
    throw new Error(`Holidays API request failed with status ${response.status}`);
  }
  const data = await response.json();
  return data.holidays.some((holiday) => holiday.is_public);
}

console.log(await isPublicHoliday('FR', '2024-01-01'));

Check a date in Python

import os
import requests


def is_public_holiday(country_code: str, iso_date: str) -> bool:
    response = requests.get(
        "https://holidaysmap.com/api/v1/holidays",
        params={
            "key": os.environ["HOLIDAYS_API_KEY"],
            "code": country_code,
            "date": iso_date,
            "format": "YYYY-MM-DD",
        },
        timeout=10,
    )
    response.raise_for_status()
    return any(holiday["is_public"] for holiday in response.json()["holidays"])


print(is_public_holiday("FR", "2024-01-01"))

Things to handle in production

• Keep the key on the server. Never ship your API key in browser code. Call the API from your backend and expose only your own endpoint.
• Check is_public. The response can include observances that are not public holidays, so filter on the is_public field.
• Cache the result. Holidays for a given country and date do not change during the day, so cache responses instead of calling the API on every page view.
• Plan for downtime. Check the API status page if requests start failing, and fall back to your cached data.

Next steps

Need holidays for a whole date range, such as a full quarter? Range queries with start and end are available on the Premium plan; see pricing. The full parameter reference is in the API documentation. To count working days across a range, read how to calculate business days excluding public holidays, and for every field in the response see the public holidays JSON format guide.