Feiertage-API Deutschland: worauf es wirklich ankommt

Was eine Feiertage-API können muss, außer Datum und Name

Datum und Name eines Feiertags liefert praktisch jede Feiertage-API, dafür braucht es kein Abonnement. Der Unterschied zeigt sich erst bei den Fällen, die eine reine Liste nicht abdeckt: Warum gilt ein Tag nur in einem Bundesland, was passiert mit einem Gedenktag, der nur ein einziges Mal im Kalender steht, und wie weit reicht die Liste in die Zukunft, wenn eine Software heute schon für 2029 planen muss.

Dazu kommt ein Punkt, der bei der Auswahl oft übersehen wird: ob die API neben Feiertagen auch die Arbeitstage eines Zeitraums direkt berechnet, oder ob eine eigene Software diese Rechnung aus der reinen Liste selbst nachbauen muss. Genau diese Fragen entscheiden, ob eine API für ein einzelnes Projekt reicht oder für eine Software, die sich auf die Werte verlässt.

Rechtsgrundlage je Bundesland

Feiertage sind in Deutschland Ländersache, nur der Tag der Deutschen Einheit ist Bundesrecht. Jedes der 16 Länder hat ein eigenes Feiertagsgesetz mit eigenem Namen und eigener Fundstelle, das Hessische Feiertagsgesetz zum Beispiel ist ein anderes Gesetz als das bayerische. Eine API, die nur allgemein gesetzliche Feiertage in Deutschland nennt, ohne Bezug auf das jeweilige Landesgesetz, verschweigt genau die Grundlage, auf die es bei einer Rückfrage oder einer Prüfung ankommt.

Bei Quellenkontor steht die Rechtsgrundlage in jeder Antwort mit: Für Hessen 2027 lautet sie Hessisches Feiertagsgesetz (HFeiertagsG). Bei einer Abfrage ohne Land kommt zusätzlich, in welchen Ländern ein Feiertag gilt, damit klar bleibt, dass ein bundesweiter Feiertag wie der 1. Mai eine andere Grundlage hat als ein Ländertag.

Regionale Feiertage

Drei gesetzliche Feiertage gelten nicht landesweit, sondern nur in einem Teil eines Bundeslands: Fronleichnam in einzelnen Gemeinden Sachsens und Thüringens, Mariä Himmelfahrt in der Mehrheit der bayerischen Gemeinden und das Augsburger Hohe Friedensfest nur in der Stadt Augsburg. Eine API, die Bayern pauschal mit oder ohne Mariä Himmelfahrt führt, liegt für einen Teil der bayerischen Standorte falsch.

Quellenkontor markiert solche Fälle mit einem eigenen Feld regional und nennt den Geltungsbereich zusätzlich als Text im Feld regional_hinweis, zum Beispiel die Landkreise, in denen Fronleichnam in Sachsen gilt. Wer nur mit Bundesland statt mit Gemeinde arbeitet, sieht daran wenigstens, dass an dieser Stelle eine zusätzliche Prüfung nötig ist, statt sich auf eine einheitliche Landesliste zu verlassen.

Einmalige Feiertage

Neben den wiederkehrenden Feiertagen gibt es einmalige: Tage, die ein Land per eigenem Gesetz für ein einziges Jahr zum Feiertag erklärt, meist aus Anlass eines runden Jahrestags. Berlin hat das gleich mehrfach getan, zuletzt für den 8. Mai 2020 zum 75. Jahrestag der Befreiung vom Nationalsozialismus und für den 8. Mai 2025 zum 80. Jahrestag desselben Ereignisses, beide Male über eine eigene Änderung des Berliner Feiertagsgesetzes befristet auf diesen einen Tag.

Eine Feiertage-API, die nur die wiederkehrende Liste aus einem Gesetzestext ausliest, übersieht solche Tage leicht, weil sie nicht im Haupttext des Gesetzes stehen, sondern in einem eigenen Änderungsgesetz mit befristeter Wirkung. Quellenkontor führt sie einzeln: Für Berlin steht schon jetzt 75. Jahrestag des Aufstands vom 17. Juni 1953 am 17.06.2028 in der Liste, obwohl das Jahr noch weit entfernt liegt.

Kriterien auf einen Blick, mit den Werten von Quellenkontor als Beispiel

Jahre im Voraus

Für eine Planung, die über das laufende Jahr hinausgeht, zählt, wie weit eine API tatsächlich reicht, nicht nur, ob sie das aktuelle Jahr abdeckt. Viele Anbieter berechnen ein Jahr erst auf Anfrage oder pflegen die Liste jährlich von Hand nach, mit der Folge, dass ein weit entferntes Jahr schlicht fehlt, bis jemand es nachträgt.

Bei Quellenkontor ist der Bereich von 2015 bis 2035 durchgängig berechnet, weil die Feiertage aus den Regeln der Landesgesetze und nicht aus einer jährlich gepflegten Liste entstehen. Für 2035, ein Jahr, das in den meisten Planungen noch nicht vorkommt, liefert derselbe Aufruf bereits 10 Feiertage für Hessen zurück, ohne separate Freischaltung oder Wartezeit.

Stichtag: wann zuletzt geprüft wurde

Eine unveränderte Liste ist nicht automatisch eine korrekte Liste. Landesgesetze ändern sich, wenn auch selten, und eine API sollte erkennen lassen, wann sie zuletzt gegen den aktuellen Gesetzestext abgeglichen wurde, nicht nur, wann sie einmal gebaut wurde.

Jede Antwort trägt deshalb ein Feld stand: Für Hessen 2027 zeigt es den 23.09.2026. Dahinter steht ein Prüfverfahren, das die 16 Feiertagsgesetze reihum kontrolliert und zusätzlich jede Woche nach neu beschlossenen einmaligen Feiertagen sucht, statt die Liste nur einmal beim Bau zu erstellen und dann liegen zu lassen.

Lizenz: was du mit den Daten machen darfst

Die Feiertage selbst stehen in Gesetzestexten und Verordnungen, amtliche Werke sind nach § 5 Urheberrechtsgesetz von vornherein gemeinfrei. Trotzdem lohnt der Blick auf die Lizenzangabe: Sie regelt nicht das Gesetz, sondern die aufbereitete, geprüfte und strukturierte Zusammenstellung, die eine API daraus macht.

Bei Quellenkontor steht das in jeder Antwort im Feld lizenz: Berechnung nach den genannten Normen. Nutzung nach den Nutzungsbedingungen von Quellenkontor. Wer stattdessen eine offene Bibliothek oder ein GitHub-Projekt nutzt, findet die Lizenzbedingungen meist in einer eigenen Datei im Projekt, häufig eine sehr freie Open-Source-Lizenz, aber ohne die laufende Prüfung gegen die Gesetzestexte, die eine kommerzielle API zusagt.

CSV, REST-API und MCP: welche Form du brauchst

Nicht jeder Anbieter deckt dieselbe Bandbreite an Zugängen ab. Manche freie Angebote wie feiertage-api.de liefern die Feiertage ausschließlich als JSON, andere wie die OpenHolidays API bieten für mehrere Länder zusätzlich ein iCal-Format zum Abonnieren an. Für eine eigene Software zählt vor allem, ob CSV für Excel-Auswertungen, ein SDK für die feste Integration und ein MCP-Server für einen KI-Agenten dazugehören, oder ob nur der reine JSON-Aufruf existiert.

Quellenkontor deckt vier Zugänge über denselben Datensatz ab: REST-API und CSV wie oben, ein SDK für JavaScript und Python, eine CLI für Skripte und Cronjobs, und einen MCP-Server, über den ein Agent das Werkzeug hr_feiertage direkt aufruft, statt ein antrainiertes, möglicherweise veraltetes Datum zu nennen.

Verfügbarkeit

Eine Feiertage-API steckt oft tief in einer Kette: Zeiterfassung, Lohnabrechnung oder ein Kalendersystem verlassen sich auf die Antwort. Ein Ausfall wirkt sich deshalb schnell auf mehrere Systeme gleichzeitig aus, stärker als bei einem einzelnen Feature einer größeren Anwendung.

Ein Blick auf die Status-Seite eines Anbieters vor der Entscheidung zeigt mehr als ein Werbeversprechen: Läuft dort eine echte Historie, oder nur ein grünes Symbol ohne weitere Angaben? Für Cronjobs, die einmal im Jahr laufen, ist ein kurzer Ausfall unkritisch, für eine Prüfung in Echtzeit bei jeder Anmeldung schon.

Checkliste vor der Wahl einer Feiertage-API

• Nennt die Antwort zu jedem Feiertag das konkrete Landesgesetz, nicht nur eine allgemeine Formulierung?
• Sind regionale Feiertage als eigenes Feld gekennzeichnet, mit Angabe des Geltungsbereichs?
• Stehen einmalige, befristete Feiertage überhaupt in der Liste, auch für künftige Jahre?
• Wie viele Jahre im Voraus lassen sich abfragen, ohne dass ein Jahr erst nachgepflegt werden muss?
• Zeigt die Antwort, wann die Liste zuletzt gegen das Gesetz geprüft wurde?
• Was sagt die Lizenz zur aufbereiteten Zusammenstellung, nicht nur zum zugrunde liegenden Gesetzestext?
• Gibt es neben JSON auch CSV, ein SDK und einen MCP-Server, oder nur einen einzelnen Zugang?

Was eine reine Feiertagsliste oft nicht mitliefert

• Die Zahl der tatsächlichen Arbeitstage in einem Zeitraum, etwa für Sollstunden oder Tagessätze: Dafür braucht es einen eigenen Arbeitstage-Rechner, der Wochenenden und Feiertage gegen ein Von-bis-Datum rechnet. Januar 2027 hat in Hessen so 20 Arbeitstage, nicht nur eine Liste einzelner freier Tage.
• Feiertage, die immer auf einen Sonntag fallen, wie Oster- und Pfingstsonntag in Brandenburg: Für Zuschläge nach § 3b EStG zählen sie trotzdem als Feiertag, eine reine Kalenderliste zeigt diesen Unterschied selten.
• Eine Kennzeichnung, ob ein Feiertag bundesweit oder nur in einem Land gilt, wenn die Abfrage mehrere Länder gleichzeitig umfasst.
• Eine maschinenlesbare Quelle je Feiertag statt eines allgemeinen Verweises auf ein Gesetz am Seitenende.

Rechtsgrundlage und Stand in der Antwort

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

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