German Public Holidays API: What Actually Matters

What a public holidays API needs beyond a date and a name

Almost every public holidays API returns a date and a name, that alone needs no subscription. The real difference shows up in the cases a plain list does not cover: why a day applies in only one state, what happens to a day of remembrance that appears on the calendar exactly once, and how far the list actually reaches into the future when software already has to plan for 2029 today.

One more point gets overlooked during selection: whether the API also computes the working days in a period directly, or whether a separate application has to rebuild that calculation from the raw list itself. These questions decide whether an API is enough for a single project or for software that relies on the values.

Legal basis by state

Public holidays are a matter for the states (Bundesländer) in Germany; only German Unity Day is federal law. Each of the 16 states has its own public holiday act with its own name and its own citation, and Hesse's law is a different law from Bavaria's. An API that names only "statutory holidays in Germany" without pointing to the relevant state law leaves out exactly the basis that matters for a follow-up question or an audit.

Quellenkontor includes the legal basis in every response: for Hesse in 2027 it reads Hessisches Feiertagsgesetz (HFeiertagsG). A call without a state additionally returns the states where a holiday applies, so it stays clear that a nationwide holiday such as May 1 rests on a different basis than a state-specific one.

Regional holidays

Three statutory holidays do not apply statewide, only in part of a state: Corpus Christi (Fronleichnam) in certain municipalities of Saxony and Thuringia, Assumption Day (Mariä Himmelfahrt) in most Bavarian municipalities, and the Augsburg Peace Festival only in the city of Augsburg. An API that marks all of Bavaria as having or lacking Assumption Day is wrong for part of Bavaria's sites either way.

Quellenkontor flags such cases with its own regional field and additionally states where it applies as text in regional_hinweis, for example the districts where Corpus Christi applies in Saxony. Anyone working at state level rather than municipality level at least sees that this point needs an extra check, instead of relying on one uniform state list.

One-off holidays

Beyond the recurring holidays, there are one-off ones: days a state declares a holiday by its own law for a single year only, usually to mark a round anniversary. Berlin has done this more than once, most recently for May 8, 2020, the 75th anniversary of the liberation from National Socialism, and for May 8, 2025, the 80th anniversary of the same event, each time through a separate amendment to Berlin's public holiday law limited to that one day.

A public holidays API that only reads the recurring list out of a law's main text can easily miss days like these, because they sit not in the main text but in a separate, time-limited amending act. Quellenkontor lists them individually: for Berlin, June 17, 2028 is already on the list, even though that year is still a long way off.

Criteria at a glance, with Quellenkontor's own values as the example

Years ahead

For planning that goes beyond the current year, what matters is how far an API actually reaches, not just whether it covers the current one. Many providers compute a year only on request or maintain the list by hand once a year, which means a distant year can simply be missing until someone adds it.

At Quellenkontor, the range from 2015 through 2035 is computed throughout, because the holidays come from the states' legal rules rather than from a manually maintained yearly list. For 2035, a year most planning does not reach yet, the same call already returns 10 holidays for Hesse, with no separate unlock or waiting period.

Point-in-time check: when it was last verified

An unchanged list is not automatically a correct one. State laws change, rarely but they do, and an API should show when it was last reconciled with the current legal text, not just when it was originally built.

Every response therefore carries a stand field (German for as-of date): for Hesse in 2027 it shows September 23, 2026. Behind it sits a review process that checks the 16 state laws in rotation and additionally searches every week for newly adopted one-off holidays, instead of building the list once and leaving it as is.

License: what you may do with the data

The holidays themselves sit in laws and ordinances, and official works are free of copyright from the outset under § 5 of Germany's Copyright Act (Urheberrechtsgesetz, UrhG). Even so, the license note is worth a look: it governs not the law itself, but the compiled, checked and structured dataset an API builds from it.

At Quellenkontor, every response carries this in a lizenz field (German for license): it points to the norms behind the calculation and states that using the compiled, checked dataset itself falls under Quellenkontor's own terms of service. Anyone using an open library or a GitHub project instead usually finds the license terms in a file within the project, often a very permissive open-source license, but without the ongoing check against the legal texts that a commercial API commits to.

CSV, REST API and MCP: which form you need

Not every provider covers the same range of access methods. Some free offerings such as feiertage-api.de return public holidays exclusively as JSON, while others such as the OpenHolidays API additionally offer an iCal format to subscribe to for several countries. For your own software, what usually matters most is whether CSV for spreadsheet analysis, an SDK for a fixed integration, and an MCP server for an AI agent are included, or whether only a plain JSON call exists.

Quellenkontor covers four access methods over the same dataset: the REST API and CSV as above, a JavaScript and Python SDK, a CLI for scripts and cron jobs, and an MCP server through which an agent calls the hr_feiertage tool directly, instead of stating a trained, possibly outdated date from memory.

Availability

A public holidays API often sits deep in a chain: time tracking, payroll or a calendar system all rely on its response. An outage therefore tends to affect several systems at once quickly, more so than a single feature failing inside one larger application.

Checking a provider's status page before deciding shows more than a marketing promise: is there an actual history there, or just a green icon with nothing behind it? For a cron job that runs once a year, a brief outage barely matters; for a real-time check on every login, it does.

Checklist before choosing a public holidays API

• Does the response name the specific state law for each holiday, rather than a generic phrase?
• Are regional holidays flagged as their own field, stating where they apply?
• Are time-limited, one-off holidays in the list at all, including for future years?
• How many years ahead can you query without a year having to be added by hand first?
• Does the response show when the list was last checked against the law?
• What does the license say about the compiled dataset, not just about the underlying legal text?
• Is there CSV, an SDK and an MCP server alongside JSON, or only a single access method?

What a plain public holidays list often does not include

• The actual number of working days in a period, for target hours or day rates: that needs a dedicated working days calculator, which computes weekends and holidays against a from-to date. January 2027 has 20 working days in Hesse this way, not just a list of individual days off.
• Holidays that always fall on a Sunday, such as Easter Sunday and Whit Sunday in Brandenburg: for premiums under § 3b of the Income Tax Act (EStG) they still count as a holiday, a distinction a plain calendar list rarely shows.
• A flag for whether a holiday applies nationwide or in only one state, when a call covers several states at once.
• A machine-readable source for each individual holiday, rather than one general reference to a law at the bottom of the page.

Legal basis and the as-of date in the response

$ curl "https://api.quellenkontor.dev/v1/hr/feiertage?jahr=2027&land=HE" \
    -H "Authorization: Bearer $QK_KEY"

# Excerpt of the response
{
  "land": "HE",
  "rechtsgrundlage": "Hessisches Feiertagsgesetz (HFeiertagsG)",
  "stand": "2026-09-23",
  "feiertage": [
    { "datum": "2027-01-01", "id": "neujahr", "name": "Neujahr", "regional": false }
  ]
}