Products

// holiday: open public holiday data

Public holidays as open data, with a source for every rule

holiday collects public holidays from official sources and publishes them as CSV, JSON, XML and iCalendar. Every rule names its legal source. The current release covers 19 countries for the years 2007 to 2035, each with a clearly described scope.

git clone holidaydownload release
  • codeMIT
  • dataCC BY 4.0
  • formatscsv · json · xml · ics
  • years2007–2035
$ cut -d';' -f1-7,12-13 dist/holidays.csv \
    | grep -E '^2026-(01-06|12-25);DE;(\*|DE-BY);'
2026-12-25;DE;*;CHRISTMAS_DAY;public;statutory;full;Christmas Day;Erster Weihnachtstag
2026-01-06;DE;DE-BY;EPIPHANY;public;statutory;full;Epiphany;Heilige Drei Könige

$

Why holiday

Apps that calculate working hours or deadlines need correct public holidays per country and region, offline and without an API call per request. Existing sources are often incomplete, paid, lack a clear licence or require you to share your work under the same licence.

How it works

  • data/rules/<COUNTRY>/*.toml

    Rules instead of date lists

    Holidays live in the repository as rules: fixed date, offset from Easter, nth weekday or weekday before a date. The data for every year is generated from them.

  • source = "https://…"

    Every rule with its legal source

    Each rule comes with its region, type, legal status, full or half day, years of validity and the official source.

  • applicability=conditional

    Conditional holidays are flagged

    Holidays that only apply under a condition are marked separately, with a readable condition. That way your app asks instead of miscalculating.

  • tests/vectors/

    Checked against official lists

    Test vectors pin down the expected dates per country and year. Where authorities provide machine-readable lists, the tests check the rules against them.

Countries in the current release

  • ATAustria
  • BEBelgium
  • CACanada · 6 regimes
  • CZCzechia
  • DEGermany
  • EEEstonia
  • FIFinland
  • FRFrance
  • GBUnited Kingdom
  • HUHungary
  • IEIreland
  • ITItaly
  • LILiechtenstein
  • LULuxembourg
  • NONorway · mainland
  • PLPoland
  • PTPortugal
  • SESweden
  • USUSA · federal

Canada covers six employment law regimes, the USA the federal holidays for federal employees. The README describes the exact scope per country.

Formats

  • dist/holidays.csv

    CSV

    One entry per line, with legal status, condition, names in English and the local language, and the source.

  • dist/holidays.json

    JSON

    The same entries as an array, ready for your application.

  • dist/holidays.xml

    XML

    For XML tools they’re available as <holiday> elements.

  • dist/ics/<JURISDICTION>.ics

    iCalendar

    All-day events for countries, states and special local calendars, ready to subscribe to in your calendar.

Quickstart

  1. Download the files from the current release or clone the repository.
  2. Build the data yourself with Nix and Task if you need your own range of years.
  3. Ask about a specific place: for Augsburg you get nationwide, Bavarian and Augsburg holidays.
  4. Take unconditional entries as they are and have conditional ones checked, say via a location lookup or a checkbox.
$ nix develop
$ task build
$ python3 tools/holidays.py query deutschland/bayern/augsburg --from 2007 --to 2026

Licences

  • Code under MIT.You’re free to use, modify and share the tools, tests and documentation.
  • Data under CC BY 4.0.You can use your own rules and generated files commercially too, with attribution.
  • No third-party datasets.The rules are written independently from official sources. Third-party holiday datasets are neither copied nor republished.

FAQ

Can I contribute?

Yes. Every new or changed rule needs an official source, such as a law, a regulation or an authority’s web page, with its address and the date it was retrieved. More in the repository.

Why are some countries missing?

A country only makes it into the release once official sources, usage rights and enough historical evidence are available. For some countries, part of that is still missing.

Does holiday replace legal advice?

No. holiday names the official source for every rule so you can check what applies.

Build with the makers

Need deadlines, working hours or calendars in your software that are actually right? Talk to us about your project.

./discuss-your-projectgit clone holiday