Einführung

OpenHolidays API ist ein kleines Open Data-Projekt, das öffentliche Daten zu gesetzlichen Feiertagen und Schulferien sammelt und über eine offene REST-API-Schnittstelle verfügbar macht. Unterstützt werden derzeit folgende Länder:

• Albanien (Feiertage und Schulferien ab 2020)
• Andorra (Feiertage und Schulferien ab 2020)
• Belarus (Feiertage und Schulferien ab 2020)
• Belgien (Feiertage und Schulferien ab 2020)
• Bulgarien (Feiertage und Schulferien ab 2020)
• Deutschland (Feiertage und Schulferien ab 2020)
• Estland (Feiertage und Schulferien ab 2020)
• Frankreich (Feiertage und Schulferien ab 2020)
• Irland (Feiertage und Schulferien ab 2020)
• Italien (Feiertage und Schulferien ab 2020)
• Kroatien (Feiertage und Schulferien ab 2020)
• Lettland (Feiertage und Schulferien ab 2020)
• Liechtenstein (Feiertage und Schulferien ab 2020)
• Litauen (Feiertage und Schulferien ab 2020)
• Luxemburg (Feiertage und Schulferien ab 2020)
• Malta (Feiertage und Schulferien ab 2020)
• Moldau (Feiertage und Schulferien ab 2020)
• Monaco (Feiertage und Schulferien ab 2020)
• Niederlande (Feiertage und Schulferien ab 2020)
• Polen (Feiertage und Schulferien ab 2020)
• Portugal (Feiertage und Schulferien ab 2020)
• Rumänien (Feiertage und Schulferien ab 2020)
• San Marino (Feiertage und Schulferien ab 2020)
• Schweden (Feiertage ab 2020)
• Schweiz (Feiertage und Schulferien ab 2020)
• Serbien (Feiertage und Schulferien ab 2020)
• Slowakei (Feiertage und Schulferien ab 2020)
• Slowenien (Feiertage und Schulferien ab 2020)
• Spanien (Feiertage und Schulferien ab 2020)
• Tschechien (Feiertage und Schulferien ab 2020)
• Ungarn (Feiertage und Schulferien ab 2020)
• Vatikanstadt (Feiertage ab 2020)
• Österreich (Feiertage und Schulferien ab 2020)

Feiertage und Ferientermine werden wahlweise als JSON oder im iCal-Format zurückgeliefert.

Los geht's¶

Der einfachste Weg, die API zu nutzen, ist der Weg über die Kommandozeile. Wir werden in diesem Kapitel mit der Kommandozeilenanwendung curl arbeiten.

Unter Linux ist curl in der Regel vorinstalliert. Unter Windows ist curl als Alias des Cmdlet Invoke-WebRequest definiert, kann also via Powershell genutzt werden. Die hier verwendeten Befehlsfolgen variieren leicht, daher werden sie für Powershell 7 (Windows) und Bash (Linux) getrennt angegeben.

Staaten¶

Zunächst fragen wir ab, welche Länder von der OpenHolidays API unterstützt werden:

curl -X GET 'https://openholidaysapi.org/Countries' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json

curl -X GET 'https://openholidaysapi.org/Countries' -H 'accept: text/json' | json_pp

Die Codes der Länder entsprechen dem Standard ISO 3166-1.

Sprachen¶

Die Namen der Feiertage bzw. Schulferien sind mehrsprachig gespeichert. In der Regel gibt es die Übersetzungen in den jeweiligen Amtssprachen eines Landes (z.B. polnisch für Polen) sowie eine Übersetzung ins Deutsche und Englische.

Die von OpenHolidays API derzeit genutzten Sprachen lassen sich wie folgt abfragen:

curl -X GET 'https://openholidaysapi.org/Languages' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json

curl -X GET 'https://openholidaysapi.org/Languages' -H 'accept: text/json' | json_pp

Die Codes der Sprachen entsprechen dem Standard ISO 639-1.

Verwaltungseinheiten¶

Pro Land können die relevanten subnationale Verwaltungseinheiten (z.B. Bundesländer, Schweizer Kantone oder Ferienzonen) abgefragt werden. Es werden nur dann Verwaltungseinheiten zurückgeliefert, wenn sie relevant für die Filterung von Feiertagen und/oder Schulferien sind.

Hier eine Beispielabfrage für Deutschland (DE):

curl -X GET 'https://openholidaysapi.org/Subdivisions?countryIsoCode=DE' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json

curl -X GET 'https://openholidaysapi.org/Subdivisions?countryIsoCode=DE' -H 'accept: text/json' | json_pp

Die Codes der Verwaltungseinheiten orientieren sich an dem Standard ISO 3166-2 sowie an der Kodierliste Hierarchical administrative subdivision codes (HASC).

Feiertage¶

Feiertage können pro Land und für einen beliebigen Zeitraum (der nicht größer als drei Jahre sein darf) abgefragt werden. Optional können die Namen der Feiertage auf eine bestimmte Sprache eingeschränkt werden.

Hier eine Beispielabfrage für Schweizer Feiertage zwischen dem 1. Januar 2022 und dem 30. Juni 2022 mit deutscher Ausgabesprache:

curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json

curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/json' | json_pp

Wer möchte, kann sich die Daten auch im iCal-Format zurückliefern lassen:

curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/calendar'

curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/calendar'

Schulferien¶

Schulferien können pro Land und Verwaltungseinheit sowie für einen beliebigen Zeitraum (der nicht größer als drei Jahre sein darf) abgefragt werden. Optional können die Namen der Schulferien auf eine bestimmte Sprache eingeschränkt werden.

Hier eine Beispielabfrage für Schulferien in Österreich zwischen dem 1. Januar 2022 und dem 31. Dezember 2022 für das Bundesland Kärnten mit englischer Ausgabesprache:

curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json

curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/json' | json_pp

Auch hier können die Daten wahlweise im iCal-Format zurückgeliefert werden:

curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar'

curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar'

Tipps und Tricks¶

Um die Bildschirmausgabe von curl in eine Datei zu schreiben, kann der Parameter -o genutzt werden. Das folgende Beispiel speichert alle deutschen Feiertage für 2022 in eine iCal-Datei, die man z.B. nach Outlook importieren kann.

curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar' -o 'kalendar.ics'

curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar' -o 'kalendar.ics'