In einigen Anwendungsbereichen habe ich mir schon ein paar mal gewünscht eine einfache API zur Hand zu haben, mit der es möglich ist Ferien- und Feiertagstermine abzurufen. Nur leider schien es sowas noch nicht zu geben. Nachdem ich dies jetzt für einen Feriencountdown wirklich brauchte, weil ich nicht alle Ferientermine für Nichts und wieder Nichts einpflegen wollte, habe ich mir schnell meine eigene HTTP API geschrieben. Mit dieser API ist es mir natürlich jetzt in allen Projekten möglich auf die Termine für Ferien und Feiertage mit einer zentralen Verwaltung zuzugreifen, zum Anderen habe ich mich aber auch dazu entschlossen die API zu öffnen und im Internet frei anzubieten.

Um es also kurz zu machen: Die API besteht aus zwei Teilen. Zum einen einer Komponente für Ferien, zum anderen aus einer Komponente für Feiertage, die getrennt voneinander arbeiten. Das beudeuted, dass es nicht möglich ist Feiertage und Ferien auf einmal abzufragen. Für Ferien erfolgt die Abfrage nach Bundesland, für Feiertage gibt es sowohl eine Abfrage für jedes Bundesland als auch Deutschlandweit. Die Antwort wird als JSON String zurückgegeben. Der genaue Aufbau ist weiter unten beschrieben.

Abfrage der Daten

Achtung: Mit der Nutzung der API stimmst du den Richtlinien für die Benutzung von APIs zu. Aus gegebenem Anlass weise ich darauf hin, dass kommerzielle Nutzer vor der Nutzung um Erlaubnis bitten müssen.

Wenn du über Aktualisierungen an der API Informiert werden möchtest, dann solltest du dich im API Newsletter eintragen.

Die Abfrage von Ferien und Feiertagen erfolgt weitesgehend auf die gleiche Art, weshalb die Abfrage hier am Beispiel von Ferien erklärt wird. Weiter unten wird dann erklärt, wie dies auf Feiertage angewendet werden kann.Für die Abfrage wird immer die EU weite Abkürzung des jeweiligen Bundeslands benötigt. Sie können aus der folgenden Tabelle entnommen werden:

Abkürzung Name
BW Baden-Württemberg
BY Bayern
BE Berlin
BB Brandenburg
HB Bremen
HH Hamburg
HE Hessen
MV Mecklenburg-Vorpommern
NI Niedersachsen
NW Nordrhein-Westfalen
RP Rheinland-Pfalz
SL Saarland
SN Sachsen
ST Sachsen-Anhalt
SH Schleswig-Holstein
TH Thüringen
DE Deutschland (Nur bei Feiertagen verfügbar)

Optional kann das Jahr mit angegeben werden. Das Jahr darf nicht kleiner als das aktuelle Jahr sein und kann maximal 5 Jahre im Voraus liegen, wobei für mehr als zwei Jahre keine (zuverlässigen) Daten vorligen, weshalb man sich nur auf das aktuelle und nächste Jahr beziehen sollte. Wird kein Jahr angegeben, so wird das aktuelle Jahr für die Abfrage benutzt. Es wird zusätzlich in der Antwort zurückgegeben, sodass festgestellt werden kann, welches Jahr ausgegeben wurde (Nur zur Sicherheit).

Also: Los gehts! Mit http://api.smartnoob.de/ferien/v1/ferien/?bundesland=nw&jahr=2015 werden die Ferien für Nordrhein-Westfahlen im Jahre 2015 ausgegeben. Für andere Bundesländer muss nw durch die entsprechende EU weite Abkürzung für das jeweilige Bundesland ersetzt werden. Um das Jahr zu ändern muss 2015 ersetzt werden.
Ein weiteres Beispiel wäre http://api.smartnoob.de/ferien/v1/ferien/?bundesland=nw. Damit werden die Ferien für das aktuelle Jahr abgerufen.

Abfrage der Feiertage

Feiertage werden im Grunde genauso abgerufen wie Ferien, allerdings wird in der Adresse dann statt ferien feiertage eingetragen. Aus den beiden obigen Beispielen wird dann also http://api.smartnoob.de/ferien/v1/feiertage/?bundesland=nw&jahr=2015 bzw. http://api.smartnoob.de/ferien/v1/feiertage/?bundesland=nw. Zusätzlich zu den normalen Bundesländern ist es auch möglich mit der Abkürzung de die deutschlandweiten Feiertage auszugeben. Für Ferien gibt es diese Option nicht.

Aufbau der Daten

Die Ergebnisse werden als JSON String zurückgegeben. Ein Beispiel kann leicht mit dieser Adresse erzeugt werden: http://api.smartnoob.de/ferien/v1/ferien/?bundesland=nw. Um auch einen Abruf der Daten direkt mit jQuery zu ermöglichen, wurde nach dieser Anleitung auch die Unterstützung für JSONP hinzugefügt.

Im Grunde empfiehlt es sich in der gewünschten Programmiersprache zu sehen, wie man an die Daten kommt. Meistens gibt es dafür schon Funktionen wie json_decode in PHP. Dennoch möchte ich hier auf zwei Dinge eingehen. Die Datumsangaben werden immer als UNIX Timestamp gespeichert. Eine Auswertung sollte so in jeder Programmiersprache problemlos möglich sein. Zum Anderen gibt es einen Fehlercode (error). Dieser kann 3 Werte annehmen:

Fehlercode Bedeutung
0 Kein Fehler, alles in Ordnung
1 Bundesland nicht vorhanden
2 Keine Daten für das ausgewählte Jahr verfügbar

Zusätzlich wird beim Auftreten eines Fehlers eine Nachricht in Textform ausgegeben, um die Fehlersuche zu erleichten. Zum Abfangen von Fehlern sollte jedoch der Fehlercode und nicht die Nachricht verwendet werden. Ein Fehlerbeispiel ist unter http://api.smartnoob.de/ferien/v1/ferien/?bundesland=nrw zu finden.

Bekannte Probleme

Wie m2andyou mir in den Kommentaren mitgeteilt hat, kann es vorkommen, dass Fehler 403 auftritt und keine Daten abgerufen werden können. Der Grund für dieses Problem ist der User Agent des Programms. Bei PHP wird besispielsweise ein Agent mit PHP 5.x übertragen.
Um vor Bot Angriffen zu schützen blockiert mein Hoster einige verdächtige User Agents. Wer also Probleme hat die Daten abzufragen, sollte erstmal versuchen den User Agent zu ändern. Nachfolgend ein Beispiel für PHP:

[php]
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, ‘http://api.smartnoob.de/ferien/v1/ferien/?bundesland=nw’);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERAGENT, ‘Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.2) Gecko/20090729 Firefox/3.5.2 GTB5’);
$ferien_json = curl_exec($ch);
[/php]

Werden die Informationen in Javascript abgerufen, kann und muss der User Agent nicht geändert werden.

Beispiel

Unter ferien.smartnoob.de habe ich einen Countdown für die Ferien in NRW online gestellt. Außerdem gibt es einen Kalendergenerator, der Ferien und Feritage aus der API abruft. Details dazu sind in diesem Artikel zu finden.

Wenn du noch Fragen oder Ideen für die API hast, dann kannst du dich gerne in den Kommentaren melden.

API Newsletter

Wie bereits oben erwähnt, biete ich einen Newsletter an, der verschickt wird, sobald ich API Versionen einstelle oder aktualisiere. Solltest du die API ernsthaft in einem Projekt benutzen, dann empfehle ich diesen hier Newsletter zu abonnieren.

31 thoughts on “Ferien / Feiertag API für Deutschland”

  1. Ahoy!
    Cooles Ding, 🙂 aber für die /feiertage/ wird im Header “Content-Type:text/html” übertragen und JSONP funktioniert da nicht. 🙁

  2. Hi,

    Danke für die API, allerdings erhalte ich gerade den Fehler 403 zurück wenn ich das ganze in meine Anwendung integrieren möchte, über den Browser geht es ohne Probleme. Habe auch schon einen anderen Webserver getestet, dort ebenfalls 403 sowohl fopen als auch file_get_contents, bei google.de geht es.

    Gruß

    1. In welcher Sprache ist die Anwendung geschrieben? Wegen dem file_get_contents gehe ich mal von PHP aus. Am besten benutzt du curl. Das ist mehr auf den Datentransfer zwischen mehreren HTTP Servern zugeschnitten. Ich vermute, dass mein Hoster den Useragent PHP irgendwas blockiert um Bots zu blockieren. Bei Curl kannst du ihn einstellen.

  3. vielleicht 2 kleine Anmerkungen..
    -beim Enddatum evtl auf 23:59:59 gehen statt auf 24 Uhr, weil das dann schon der nächste Tag ist.
    -bei den Pfingstferien sollte man sich evtl eine besser Darstellung überlegen, da zb in Berlin nicht von-bis ist sondern 2 verschiedene Tage.

    Ansonsten gute Arbeit, dann musst ich mir wenigstens nicht überlegen, wie ich es an schlausten aus den pdf’s des kmk parsen muss

    1. Eine Sekunde abzuziehen ist an sich eine gute Idee. Allerdings muss ich dafür eine neue API Version erstellen.
      Eine Lösung, um zwei Tage zurückzugeben wäre jeder Art von Ferien eine eigene ID zuzuordnen oder den Termin in JSON zu verschachteln. Zumindest letzteres würde also auch eine neue API Version bedeuten.
      Früher oder später kann ich das implementieren aber von heute auf morgen geht das nicht, weil ich auch noch einige Änderungen im Hintergrund durchführen muss.

      1. oh so war das auch nicht gemeint, nur paar Gedankenanstöße, falls du mal wieder an der API basteln möchtest..
        Für die Pfingstferien könnte man es evtl auch aufteilen in Himmelfahrt und Pfingsten, so ist es wohl auch gedacht vom kmk.

  4. Hey, eine Frage:
    Ist es möglich, 2 Jahre gleichzeitig abzurufen? Denn momentan wird bei zB “http://api.smartnoob.de/ferien/v1/ferien/?bundesland=he&jahr=2015&jahr=2016” nur die Daten für 2016 ausgegeben.

    Gruß

    1. Die Ausgabe von zwei Jahren gleichzeitig ist nicht möglich. Wenn du jahr=2015&jahr=2016 als URL Parameter angibst, setzt du die Variable jahr erst gleich 2015, um sie dann mit 2016 zu überschreiben. D.h. der Server erhält nur noch 2016. Die einzige Möglichkeit wäre, dass ich da eine Zusatzfunktion implementiere, die entweder Variablen wie jahr1, jahr2 etc. akzeptiert, oder die mehrere Jahre JSON kokodiert einliest.

      1. Denkst du, es wäre ein großer Aufwand für dich, so etwas zu implementieren? Denn generell wurde es ja Sinn machen, Ferien für 2 Jahre abzurufen, denn ein Schuljahr geht auch über 2 Jahre hinweg 🙂
        Gruß

        1. Sinn machen würde das auf jeden Fall. Das Problem ist allerdings, dass ich für die Rückgabe mehrere Jahre das JSON neu verschachteln müsste, was eine neue API Version bedeuten würde.
          Das zieht einiges an Aufwand nach sich, weil ich dann unter anderem meine Richtlinien einhalten müsste und die Nutzer über die neue Version informieren müsste. Es gab hier aber noch ein oder zwei andere Vorschläge, sodass ich denke, dass es langsam mal Sinn macht von vorne anzufangen und alle Verbesserungen zu implementieren.

          1. Und, schon irgendwas neues geplant?
            Hätte ansonsten noch den Vorschlag, das Datumsformat in ein anderes zu ändern, ein einfaches TTMMYYY würde es auch locker tun 🙂

          2. Geplant ist was neues mit dem anstehenden Serverumzumg im Dezember/Januar. Die TTMMYYYY sehe ich als zusätzliche Möglichkeit der Ausgabe an, aber keineswegs als Ersatz für den Timestamp. Timestamps sind einfach viel zu weit verbreitet und können von den meisten Programmiersprachen viel leichter verarbeitet werden als TTMMYYYY das könnte. Daher bin ich der Meinung, dass der timestamp nicht komplett verschwinden sollte, ein anderes Datumsformat könnte man aber natürlich zusätzlich anbieten.

    2. Wenn du die Daten über mehere Jahre abfragen möchtest, kannst du besser für jedes Jahr ein einzelnes Array (oder was auch immer) füllen.
      Robin müsste sonst für jedes Jahr einen URL-Parameter erstellen.

  5. Hallo Robin, vielen Dank für diese API. Wir nutzen Deine API in unserer Verwaltungssoftware zur Schuljahresplanung. Deine API ist einfach funktioniert einwandfrei und ist eine sehr große Hilfe. Beste Grüße, Clemens Fricke

  6. Hallo Robin,

    Ferientage werden ja jedes Jahr neu je Bundesland verhandelt. Wann genau trägst du die Daten ein? Gibt es hier einen Automatismus?

    Hast du eine verlässliche Quelle?

    Grüße
    Thomas

    1. Als Quelle der Daten verwende ich Schulferien.org. Die bieten fertige iCal Dateien an, die ich einfach nur parse und dann automatisch in der Datenbank aktualisiere. Einen automatismus der regelmäßig aufgerufen wird gibt es dabei nicht, ich starte das entsprechende Script aber mindestens einmal jährlich, sodass die verfügbaren Daten ausreichen sollten.

  7. Vielen Dank für diese API, ein sehr praktisches Tool! Aber einen Punkt habe ich dennoch: gibt es eine Möglichkeit, nur die gesetzlichen Feiertage für ganz Deutschland zu bekommen (i.e. jene, die in allen Ländern gelten)?

    1. Sieh dir die Tabelle nochmal genau an 😉 Der Abruf von bundesweiten Feitergaben erfolgt über das Kürzel de im Parameter Bundesland.

      1. Ja, das habe ich ausprobiert, aber da kommen Feiertage wie “Weiberfastnacht” oder “Barbara” die kein Mensch kennt und die garantiert keine gesetzlichen Feiertage für ganz Deutschland sind!

        1. Das ist natürlich nicht so ideal. Da bleibt eigentlich nur Zusammentragen der Feiertage in den einzelnen Bundesländern.

  8. Du schreibst: “Das Jahr darf nicht kleiner als das aktuelle Jahr sein…”. Defacto sind aber die Ferien für 2015 und 2014 durchaus abrufbar. Ich brauche für die Abrechnungen jeweils auch das jeweils vergangene Jahr. Wird das langfristig verfügbar bleiben oder wirst Du die alten Daten irgendwann löschen? Gerade um die Jahreswende herum kann ich mir vorstellen dass viele Anwendungen auch das alte Jahr noch benötigen.

    1. Ich hatte eigentlich nicht die Absicht diese Daten langfristig zu halten. Das ich sie bisher noch nicht gelöscht habe ist reiner Zufall. Ich kann ohnehin schon nicht für die Verfügbarkeit der aktuellen Daten garantieren, wie sollte ich es dann für die Vergangenheit können? Es kann Glück sein, wenn die Daten verfügbar sind, aber bei Änderungen an der API würde ich die alten Daten nicht migrieren, sodass sie verloren wären. Der Aufwand dazu ist mir einfach zu groß.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.