API-Referenz

← Zurück zur API-Übersicht

Diese Seite beschreibt allgemeine Konzepte, Response-Formate und Parameter, die in der gesamten API v2.1 verwendet werden.

Response-Format

Alle API v2.1 JSON-Antworten folgen einem einheitlichen Format mit zwei Hauptfeldern: 

{
  "data": [ /* Array von Objekten oder einzelnes Objekt */ ],
  "meta": {
    "api_version": "2.1"
  }
}

Daten-Feld

Das data-Feld enthält die eigentlichen Daten:

  • Bei Listen-Endpunkten (z.B. /federal-states): Ein Array von Objekten
  • Bei Detail-Endpunkten (z.B. /federal-states/bayern): Ein einzelnes Objekt
  • Bei spezialisierten Endpunkten (z.B. /bridge-days): Ein Objekt mit strukturierten Daten

Meta-Feld

Das meta-Feld enthält zusätzliche Informationen über die Antwort:

  • api_version: Version der API (immer "2.1")
  • location: Bei Periods-Endpunkten - Informationen über den Standort
  • date_range: Bei Periods-Endpunkten - Der angefragte Zeitraum

Fehlerbehandlung

Bei Fehlern wird ein JSON-Objekt mit einem errors-Array zurückgegeben: 

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Federal state not found"
    }
  ]
}

HTTP-Status-Codes

Status-Code Bedeutung Beschreibung
200 OK Erfolg Anfrage erfolgreich verarbeitet
400 Bad Request Ungültige Anfrage Fehlende oder ungültige Parameter
404 Not Found Nicht gefunden Ressource existiert nicht
500 Internal Server Error Serverfehler Unerwarteter Fehler auf dem Server

Query-Parameter

Verschiedene Endpunkte unterstützen Query-Parameter zur Filterung und Anpassung der Ergebnisse:

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, bridge-days Jahr (YYYY)
vacation_types icalendar school (nur Schulferien) oder all (Ferien + Feiertage)
calendar_year icalendar true für Kalenderjahr, false für Schuljahr
federal_state cities, counties, schools Filterung nach Bundesland (Slug)
city schools Filterung nach Stadt (Slug)
country federal-states Filterung nach Land (Slug)

Datumsformate

Alle Daten in der API verwenden das ISO 8601 Format:

  • Datum: YYYY-MM-DD (z.B. "2025-01-15")
  • Datum mit Zeit: YYYY-MM-DDTHH:MM:SSZ (z.B. "2025-01-15T10:30:00Z")

Standorttypen

Die API unterstützt folgende Standorttypen, die in einem type-Feld zurückgegeben werden:

Typ Beschreibung Beispiel
country Land Deutschland
federal_state Bundesland Bayern
county Landkreis München (Landkreis)
city Stadt München
school Schule Gymnasium München Nord

Content-Types

Die API unterstützt verschiedene Content-Types je nach Endpunkt:

Endpunkt-Typ Content-Type
JSON-Endpunkte application/json
iCalendar-Export text/calendar; charset=utf-8
vCard-Export text/vcard; charset=utf-8
PDF-Dokumente application/pdf

Tipp: Alle API-Endpunkte sind öffentlich zugänglich und erfordern keine Authentifizierung. Bitte beachten Sie faire Nutzungsgrenzen und cachen Sie Antworten wenn möglich.

Rate Limiting

Derzeit gibt es keine festen Rate Limits für die API. Wir bitten jedoch um:

  • Angemessene Nutzung der API
  • Caching von Antworten wenn möglich
  • Vermeidung von unnötigen wiederholten Anfragen

Bei missbräuchlicher Nutzung behalten wir uns vor, Rate Limits einzuführen oder den Zugriff zu beschränken.

Siehe auch