Im Rahmen eines Projektes benötigte ich einen einfachen Zugriff auf deutsche Ferientermine über eine einfach zu benutzende JSON-Schnittstelle. Abgesehen von Feiertagen bin bin ich leider nicht fündig geworden.
Um für meine Projekte dieses Problem zu lösen, habe ich den Ferien-Webservice entwickelt. Diese stellt für alle deutschen Bundesländer die Ferientermine für die Jahre 2017, 2018, 2019, 2020 und 2021 über eine API als XML oder JSON zur Verfügung.
Die Benutzung ist für private und kommerzielle Zwecke kostenfrei. Bitte bedenke bei der Verwendung, dass ich keine kommerziellen Zwecke verfolge und die Hostingkosten für dieses Projekt aus meiner eigenen Tasche trage. Sämtliche Änderungen passieren in meiner Freizeit. Ich habe mittlerweile keine Verwendung mehr für diese Daten.
Sämtliche Datumsangaben sind ohne Gewähr. Ich übernehme weder Verantwortung für die Richtigkeit der Daten noch hafte ich für Schäden die aus der Verwendung dieser API entstehen. Ich behalte mir vor, die API jederzeit - ohne vorherige Ankündigung - einzustellen oder zu ändern. Wenn du sicher sein möchtest dass diese Daten stimmen und Erreichbarkeit sicherstellen möchtest, solltest du dieses Projekt selber hosten und mit von dir geprüften Kalenderdaten füttern. Die Anleitung dazu findest du im dazugehörigen GitHub-Repository.
Hier entlang zum GitHub-Repository
Die Schnittstelle ist unter https://ferien-api.de/api/v1/holidays erreichbar.
Du kannst die API direkt über Swagger / OpenAPI ausprobieren: Swagger / OpenAPI.
Dort kannst du dir auch
für die Sprache und das Framework Deiner Wahl Client SDKs generieren.
Um alle kommenden Ferientermine für alle Bundesländer zu erhalten, starte wie folgt:
$ curl https://ferien-api.de/api/v1/holidays
[
{
"start":"2017-04-09T22:00",
"end":"2017-04-21T22:00",
"year":2017,
"stateCode":"BW",
"name":"osterferien",
"slug":"osterferien-2017-BW"
},..
]
Die Datumsangaben werden als UTC zurückgeliefert.
Alle Ferientermine für ein Bundesland erhältst du über
https://ferien-api.de/api/v1/holidays/{stateCode},
wobei stateCode dem zweistelligen Code des Bundeslandes entspricht.
$ curl https://ferien-api.de/api/v1/holidays/HB
[
{
"start":"2017-01-29T23:00",
"end":"2017-01-31T23:00",
"year":2017,
"stateCode":"HB",
"name":"winterferien",
"slug":"winterferien-2017-HB"
},
{
"start":"2017-04-09T22:00",
"end":"2017-04-22T22:00",
"year":2017,
"stateCode":"HB",
"name":"osterferien",
"slug":"osterferien-2017-HB"
},..
]
Die möglichen Codes für die Bundesländer findest du zum Beispiel unter https://de.wikipedia.org/wiki/ISO_3166-2:DE.
Alle Ferientermine nach Bundesland und erhältst du über https://ferien-api.de/api/v1/holidays/{stateCode}/{year}.
$ curl https://ferien-api.de/api/v1/holidays/HB/2017
[
{
"start":"2017-01-29T23:00",
"end":"2017-01-31T23:00",
"year":2017,
"stateCode":"HB",
"name":"winterferien",
"slug":"winterferien-2017-HB"
},
{
"start":"2017-04-09T22:00",
"end":"2017-04-22T22:00",
"year":2017,
"stateCode":"HB",
"name":"osterferien",
"slug":"osterferien-2017-HB"
},..
]
Du kannst das Format der zurückgelieferten Daten ändern indem du einfach .json oder .xml an das Ende der URL anhängst.
| Feld | Typ | Beschreibung |
|---|---|---|
| start | Date ISO8601 (UTC) | Ferienbeginn |
| end | Date ISO8601 (UTC) | Ferienende |
| stateCode | String | Zweistelliger Code des Bundeslandes |
| name | String | Name der Schulferien |
| slug | String | Kombination aus Ferienname, Jahr und Bundesland |
| Feld | Typ | Länge |
|---|---|---|
| StateCode | String (siehe https://de.wikipedia.org/wiki/ISO_3166-2:DE) | 2 |
| Year | Int | 4 |
Dieses Projekt ist unter der MIT License lizenziert. Du findest den Quellcode auf GitHub unter https://github.com/paulbrejla/ferien-api. Dort kannst du dich direkt an der Weiterentwicklung beteiligen.
Die Ferien-Schnittstelle ist ein Projekt von Paul Brejla. Für Featurewünsche oder Bugs kannst du gerne ein Issue oder einen Pull Request unter https://github.com/paulbrejla/ferien-api eröffnen. Bei Rückfragen kannst du weiter unten einen Kommentar hinterlassen oder mich unter paul(at)paulbrejla(punkt)com erreichen.