Informationen für Entwickler
Das Open-Source-Projekt
mehr-schulferien.de ist ein mit der Programmiersprache Elixir und dem Phoenix Framework geschriebenes Open-Source-Projekt (MIT Lizenz). Der Code wird auf https://github.com/mehr-schulferien-de/www.mehr-schulferien.de gehostet und dort findet die Entwicklungsarbeit statt.
Wir freuen uns über gute Feature-Requests und Bug-Reports! Idealerweise als Issues auf Github , aber auch gerne per E-Mail an Stefan Wintermeyer (sw@wintermeyer-consulting.de)
URL-Parameter
Verschiedene Ansichten können über URL-Parameter angepasst werden. Die Ferienübersicht unter / unterstützt folgende Parameter:
| Parameter | Typ | Beschreibung | Beispiel |
|---|---|---|---|
| today | String | Startdatum im Format DD.MM.YYYY | today=01.09.2024 |
| days | Integer | Anzahl der anzuzeigenden Tage (1-365) | days=180 |
Beispiel mit kombinierten Parametern: /?today=01.09.2024&days=180
Weitere Informationen finden Sie in der Dokumentation auf GitHub .
Die API
Alle Daten können per RESTful JSON-API abgerufen werden. Wir bieten zwei API-Versionen an:
Empfehlung: Verwenden Sie API v2.1 für neue Integrationen. Die v2.0 API ist veraltet und wird nur noch aus Kompatibilitätsgründen unterstützt.
API v2.1 (Empfohlen)
Die API v2.1 bietet eine klare Struktur mit dedizierten Endpunkten für jeden Standorttyp. Dies verhindert Mehrdeutigkeiten, wenn mehrere Standorte denselben Slug haben (z.B. "Hessen" als Bundesland und als Stadt).
Verfügbare Endpunkte
| Standorttyp | Basis-URL | Verfügbare Aktionen |
|---|---|---|
| Bundesländer | /api/v2.1/federal-states | Liste, Details, Ferien, iCalendar |
| Städte | /api/v2.1/cities | Liste, Details, Ferien, iCalendar |
| Landkreise | /api/v2.1/counties | Liste, Details, Ferien, iCalendar |
| Schulen | /api/v2.1/schools | Liste, Details, Ferien, iCalendar, vCard |
Beispiele: Standorte abrufen
-
Alle Bundesländer:
curl -H "Accept: application/json" https://www.mehr-schulferien.de/api/v2.1/federal-states
-
Spezifisches Bundesland:
curl -H "Accept: application/json" https://www.mehr-schulferien.de/api/v2.1/federal-states/hessen
-
Alle Städte:
curl -H "Accept: application/json" https://www.mehr-schulferien.de/api/v2.1/cities
Beispiele: Feriendaten abrufen
-
Ferien für ein Bundesland:
curl -H "Accept: application/json" https://www.mehr-schulferien.de/api/v2.1/federal-states/bayern/periods?start_date=2024-01-01&end_date=2024-12-31
-
Nur Schulferien für eine Stadt:
curl -H "Accept: application/json" https://www.mehr-schulferien.de/api/v2.1/cities/muenchen/periods?type=vacation&start_date=2024-01-01&end_date=2024-12-31
-
Nur Feiertage für einen Landkreis:
curl -H "Accept: application/json" https://www.mehr-schulferien.de/api/v2.1/counties/muenchen-landkreis/periods?type=holiday&start_date=2024-01-01&end_date=2024-12-31
iCalendar Export
Exportieren Sie Feriendaten im iCalendar-Format (.ics) für die direkte Integration in Kalenderanwendungen:
-
Schuljahr 2024/2025 für Bayern:
curl https://www.mehr-schulferien.de/api/v2.1/federal-states/bayern/icalendar?year=2024&vacation_types=school
-
Kalenderjahr 2024 für München (alle Ferien & Feiertage):
curl https://www.mehr-schulferien.de/api/v2.1/cities/muenchen/icalendar?year=2024&vacation_types=all&calendar_year=true
-
Nur Schulferien für eine spezifische Schule:
curl https://www.mehr-schulferien.de/api/v2.1/schools/gymnasium-muenchen-nord/icalendar?year=2024&vacation_types=school
vCard Export (nur für Schulen)
Exportieren Sie Schulkontaktdaten als vCard:
curl https://www.mehr-schulferien.de/api/v2.1/schools/gymnasium-muenchen-nord/vcard
API Response Format
Alle API v2.1 Antworten folgen einem einheitlichen JSON-Format:
{
"data": [ /* Array von Objekten oder einzelnes Objekt */ ],
"meta": {
"api_version": "2.1"
}
}
Query Parameter
| Parameter | Endpunkte | Beschreibung |
|---|---|---|
| start_date | periods | Startdatum im Format YYYY-MM-DD |
| end_date | periods | Enddatum im Format YYYY-MM-DD |
| type | periods | vacation (nur Ferien) oder holiday (nur Feiertage) |
| year | icalendar | Jahr für den Export (Standard: aktuelles Jahr) |
| vacation_types | icalendar | school (nur Schulferien) oder all (alle) |
| calendar_year | icalendar | true für Kalenderjahr, sonst Schuljahr |
Vollständige API v2.1 Dokumentation: API v2.1 Referenz auf GitHub
API v2.0 (Veraltet)
Hinweis: Die API v2.0 ist veraltet und wird nur noch aus Kompatibilitätsgründen unterstützt. Bitte verwenden Sie für neue Integrationen die API v2.1, da diese eindeutige Endpunkte für jeden Standorttyp bietet und das Problem mit mehrdeutigen Slugs (z.B. "Hessen" als Bundesland und Stadt) löst.
locations
Das Model Locations wird für die Speicherung von Ländern (countries), Bundesländern (federal_states), Landkreisen (counties), Städten (cities) und Schulen (schools) benutzt. Die Dabei werden die einzelnen Ebenen mit einander verknüpft.
Beispiel
-
Daten zu Deutschland abrufen:
curl -H "Content-Type: application/json" http://www.mehr-schulferien.de/api/v2.0/locations/1
-
Daten zu allen Locations abrufen:
curl -H "Content-Type: application/json" http://www.mehr-schulferien.de/api/v2.0/locations
periods
Das Model Period wird zur Speicherung der einzelnen Ferien und Feiertage benutzt.
Beispiel
-
Daten zum Eintrag mit der ID 23 abrufen:
curl -H "Content-Type: application/json" http://www.mehr-schulferien.de/api/v2.0/periods/23
-
Daten zu allen Einträgen abrufen:
curl -H "Content-Type: application/json" http://www.mehr-schulferien.de/api/v2.0/periods
holiday_or_vacation_types
Das Model HolidayOrVacationType wird zur Speicherung der einzelnen Arten von Ferien und Feiertage benutzt.
Beispiel
-
Daten zum Eintrag mit der ID 10 abrufen:
curl -H "Content-Type: application/json" http://www.mehr-schulferien.de/api/v2.0/holiday_or_vacation_types/10
-
Daten zu allen Einträgen abrufen:
curl -H "Content-Type: application/json" http://www.mehr-schulferien.de/api/v2.0/holiday_or_vacation_types
Noch Wünsche an die API?
Mit der aktuellen API haben Sie Zugriff auf alle Daten, müssen diese aber noch selber verarbeiten. In Zukunft werden wir auch Anfragen wie "Ist heute ein Feiertag" per API beantworten. Wenn Sie dazu Wünsche oder Vorschläge haben, würden wir uns über ein entsprechendes Feature-Request- Issues auf Github freuen.