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:

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:

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.