Deutsche Ferientermine

Via JSON -und XML-Schnittstelle


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.

Verwendung (bitte lies mich, wirklich!)

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.

Richtigkeit und Bereitstellung der 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
Wenn die Schnittstelle für dich nützlich ist, freue ich mich aber über eine Spende für einen Kaffee.

Hello World

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.

Ferientermine nach Bundesland

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.

Ferientermine nach Bundesland und Jahr

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"
           },..
        ]
       

Rückgabewert & Format

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
Parameter
Feld Typ Länge
StateCode String (siehe https://de.wikipedia.org/wiki/ISO_3166-2:DE) 2
Year Int 4


Mithelfen

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.


Kontakt und Feedback

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.

Impressum
Paul Brejla
Gerberbruch 15
18055 Rostock