Open public holiday data: JSON and ICS

Endpoints (stable, version 1)

All files are static and cached for one day. Country code = ISO 3166-1 alpha-2 in lower case, region codes = ISO 3166-2 without the country prefix.

https://toolboxday.com/data/v1/holidays/index.json
https://toolboxday.com/data/v1/holidays/{country}/{year}.json
https://toolboxday.com/data/v1/holidays/{country}/{year}.ics

index.json · /data/v1/holidays/de/2027.json · /data/v1/holidays/fr/2027.ics

{
  "date": "2027-01-06",
  "id": "heiligeDreiKoenige",
  "name": "Epiphany",
  "localName": "Heilige Drei Könige",
  "nationwide": false,
  "regions": [
    "BW",
    "BY",
    "ST"
  ]
}

Code examples

JavaScript

const res = await fetch('https://toolboxday.com/data/v1/holidays/de/2027.json');
const data = await res.json();
// nationwide holidays + holidays of one state (e.g. Bavaria = "BY")
const byState = data.holidays.filter(
  (h) => h.nationwide || h.regions?.includes('BY')
);
console.log(byState.map((h) => `${h.date} ${h.name}`));

Python

import json, urllib.request

url = "https://toolboxday.com/data/v1/holidays/de/2027.json"
data = json.load(urllib.request.urlopen(url))
for h in data["holidays"]:
    where = "nationwide" if h["nationwide"] else ", ".join(h["regions"])
    print(h["date"], h["name"], "-", where)

curl + jq

curl -s https://toolboxday.com/data/v1/holidays/de/2027.json | jq '.holidays[] | select(.nationwide) | .date'

Subscribe in your calendar

The ICS files contain the nationwide public holidays. Google Calendar: “Other calendars → From URL”; Outlook: “Add calendar → Subscribe from web”; iPhone: “Settings → Calendar → Accounts → Add Subscribed Calendar”.

https://toolboxday.com/data/v1/holidays/fr/2027.ics

How the data is checked

• Germany: computed from the 16 state holiday laws and the Unification Treaty, with automated tests against the legal texts.
• Other countries: generated with python-holidays and cross-checked against Nager.Date and Google’s public holiday calendars. Countries, years or regions with a mismatch are not included here.
• Holidays based on the lunar calendar carry “estimated”: the date may shift by one day depending on the moon sighting. No warranty – for legally binding purposes, the official source prevails.

School holidays

The JSON files for Germany also contain the school holidays of all 16 states (source: KMK and state ministries of education), as far as officially published.

School holidays of further countries (from the OpenHolidays API) are available as a separate file under the Open Database License (ODbL 1.0): /data/schulferien-welt.json

Found an error or missing a country? Write to us: info@saracai.de