Datum-Abfragen API

← Zurück zur API-Übersicht

Die Datum-Abfragen API ermöglicht es, schnell und einfach zu überprüfen, ob ein bestimmtes Datum ein Feiertag, Schultag oder Ferientag ist. Ideal für Kalender-Apps, Planungstools oder einfache Abfragen wie "Ist heute schulfrei in Bayern?".

Verfügbare Endpunkte

1. Feiertag prüfen

Prüft, ob ein bestimmtes Datum ein gesetzlicher Feiertag ist. 

GET /api/v2.1/queries/is-public-holiday?location_slug=bayern&date=2025-12-25

Curl-Beispiel:

curl "https://www.mehr-schulferien.de/api/v2.1/queries/is-public-holiday?location_slug=bayern&date=2025-12-25"

Query-Parameter:

  • location_slug (erforderlich): Slug des Standorts (Bundesland, Stadt oder Schule)
  • date (optional): Datum im Format YYYY-MM-DD. Standard: heute

Beispiel-Antwort:

{
  "data": {
    "date": "2025-12-25",
    "location": {
      "name": "Bayern",
      "slug": "bayern",
      "type": "federal_state"
    },
    "is_public_holiday": true,
    "holidays": [
      {
        "name": "1. Weihnachtstag",
        "starts_on": "2025-12-25",
        "ends_on": "2025-12-25"
      }
    ]
  },
  "meta": {
    "api_version": "2.1"
  }
}

2. Schultag prüfen

Prüft, ob ein bestimmtes Datum ein Schultag ist (kein Wochenende, kein Feiertag, keine Ferien). 

GET /api/v2.1/queries/is-school-day?location_slug=bayern&date=2025-09-15

Curl-Beispiel:

curl "https://www.mehr-schulferien.de/api/v2.1/queries/is-school-day?location_slug=bayern&date=2025-09-15"

Query-Parameter:

  • location_slug (erforderlich): Slug des Standorts (Bundesland, Stadt oder Schule)
  • date (optional): Datum im Format YYYY-MM-DD. Standard: heute

Beispiel-Antwort:

{
  "data": {
    "date": "2025-09-15",
    "location": {
      "name": "Bayern",
      "slug": "bayern",
      "type": "federal_state"
    },
    "is_school_day": true,
    "school_free_periods": []
  },
  "meta": {
    "api_version": "2.1"
  }
}

3. Umfassende Datum-Prüfung

Liefert einen umfassenden Status für ein Datum: Feiertag, Schultag, Ferien, Wochenende und eine menschenlesbare Erklärung. 

GET /api/v2.1/queries/check-date?location_slug=bayern&date=2025-12-25

Curl-Beispiel:

curl "https://www.mehr-schulferien.de/api/v2.1/queries/check-date?location_slug=bayern&date=2025-12-25"

Query-Parameter:

  • location_slug (erforderlich): Slug des Standorts (Bundesland, Stadt oder Schule)
  • date (optional): Datum im Format YYYY-MM-DD. Standard: heute

Beispiel-Antwort:

{
  "data": {
    "date": "2025-12-25",
    "location": {
      "name": "Bayern",
      "slug": "bayern",
      "type": "federal_state"
    },
    "is_public_holiday": true,
    "is_school_day": false,
    "is_school_vacation": true,
    "is_weekend": false,
    "public_holidays": [
      {
        "name": "1. Weihnachtstag",
        "starts_on": "2025-12-25",
        "ends_on": "2025-12-25"
      }
    ],
    "school_vacations": [
      {
        "name": "Weihnachtsferien",
        "colloquial": "Weihnachtsferien",
        "starts_on": "2025-12-24",
        "ends_on": "2026-01-05"
      }
    ],
    "explanation": "1. Weihnachtstag und Weihnachtsferien"
  },
  "meta": {
    "api_version": "2.1"
  }
}

Praktische Anwendungsfälle

Ist heute Feiertag in Hessen?

GET /api/v2.1/queries/is-public-holiday?location_slug=hessen

Ist morgen schulfrei in Berlin?

GET /api/v2.1/queries/check-date?location_slug=berlin&date=<morgen>

Hinweis: <morgen> durch tatsächliches Datum ersetzen

Umfassender Status für eine spezifische Schule an einem bestimmten Datum 

GET /api/v2.1/queries/check-date?location_slug=85354-gymnasium-freising&date=2025-07-28

Standort-Typen

Die Datum-Abfragen funktionieren mit folgenden Standort-Typen:

  • Bundesländer (z.B. bayern, hessen, berlin)
  • Städte (z.B. muenchen, frankfurt-am-main)
  • Schulen (z.B. 85354-gymnasium-freising)

Tipp: Verwenden Sie die Standorte API um verfügbare Slugs zu finden.

Fehlerbehandlung

Die API gibt folgende HTTP-Status-Codes zurück:

Status-Code Bedeutung
200 OK Erfolg
400 Bad Request Ungültiges Datumsformat
404 Not Found Standort nicht gefunden

Beispiel-Fehlermeldung:

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

Performance-Tipp: Die API berechnet Datum-Status on-the-fly. Für wiederholte Abfragen desselben Zeitraums empfehlen wir, die Periods API zu verwenden und die Ergebnisse lokal zu cachen.

Siehe auch