Achtung: Die API wird zum 01.01.2020 eingestellt. Mehr dazu erfährst du hier.

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.

Subscribe
Notify of
37 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
eiszfuchs
9 years ago

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

eiszfuchs
9 years ago
Reply to  robin

Schaut super aus! o/

m2andyou
9 years ago

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ß

m2andyou
9 years ago
Reply to  robin

Danke für den Hinweis, es liegt tatsächlich am Useragent.

9 years ago

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

8 years ago
Reply to  robin

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.

8 years ago

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ß

8 years ago
Reply to  robin

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ß

8 years ago
Reply to  robin

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 🙂

Thomas
8 years ago
Reply to  DominikTV

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.

Clemens
8 years ago

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

Thomas
8 years ago

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

8 years ago

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)?

8 years ago
Reply to  robin

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!

[…] einiger Zeit habe ich meine Ferien / Feiertage API veröffentlicht. Mit ihr ist es möglich die Daten für Ferien und Feiertage nach Bundesland bzw. […]

8 years ago

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.

Sudhir Batra
7 years ago

Super tolle API. Gibt es diese vielleicht auch für die österreichischen Daten?

Maximilian
5 years ago

Ist eigentlich eine neue API Version verfügbar?

Marvin
5 years ago

Hey leider ist deine api zur Zeit nicht erreichbar.
Fehler: HTTP 301 Moved Permanently

Paul
4 years ago

Die Feiertage für ab 2021 sind noch nicht verfügbar. Wann werden die zur Verfügung gestellt. Bräuchte die Feiertage für die nächsten 5 Jahre.
Viele Grüße