Urlaubsplaner API

← Zurück zur API-Übersicht

Die Urlaubsplaner-Endpunkte berechnen optimale Urlaubszeiträume für eine bestimmte Anzahl von Urlaubstagen. Der Algorithmus findet die Zeitfenster mit der höchsten Effizienz, indem er Feiertage und Wochenenden optimal nutzt.

Verfügbare Endpunkte

Methode Endpunkt Beschreibung
GET /api/v2.1/federal-states/:slug/vacation-optimizer Optimale Urlaubsfenster für ein Bundesland (JSON)
GET /api/v2.1/federal-states/:slug/vacation-optimizer/icalendar Optimale Urlaubsfenster als iCal-Download

Query-Parameter

  • year (optional): Das Jahr für die Berechnung (Standard: aktuelles Jahr). Erlaubter Bereich: aktuelles Jahr -5 bis +3.
  • days (erforderlich): Anzahl der Urlaubstage (1-60)
  • variant (optional): normal (Standard) oder budget (außerhalb der Schulferien für günstigeres Reisen)
  • top (optional): Anzahl der zurückgegebenen Top-Ergebnisse (Standard: 5)

Beispiel

Request 

GET https://www.mehr-schulferien.de/api/v2.1/federal-states/bayern/vacation-optimizer?year=2026&days=10

Response 

{
  "data": {
    "location": {
      "id": 2,
      "name": "Bayern",
      "slug": "bayern",
      "type": "federal_state"
    },
    "year": 2026,
    "vacation_days_requested": 10,
    "variant": "normal",
    "summary": {
      "best_total_free_days": 17,
      "best_efficiency_percentage": 70,
      "opportunities_found": 5
    },
    "optimal_windows": [
      {
        "rank": 1,
        "starts_on": "2026-04-18",
        "ends_on": "2026-05-04",
        "vacation_days_used": 10,
        "total_free_days": 17,
        "breakdown": {
          "vacation_days": 10,
          "weekend_days": 6,
          "holiday_days": 1
        },
        "efficiency_percentage": 70,
        "spans_year_boundary": false,
        "includes_school_vacation": false,
        "related_holidays": ["Tag der Arbeit"]
      }
    ],
    "cross_year_option": null,
    "links": {
      "web_page": "https://www.mehr-schulferien.de/urlaubsplaner/bayern/10-tage/2026",
      "icalendar": "https://www.mehr-schulferien.de/api/v2.1/federal-states/bayern/vacation-optimizer/icalendar?year=2026&days=10"
    }
  },
  "meta": {
    "api_version": "2.1"
  }
}

Response-Felder

  • location: Informationen über das Bundesland
  • year: Das angefragte Jahr
  • vacation_days_requested: Anzahl der angefragten Urlaubstage
  • variant: "normal" oder "budget"
  • summary: Zusammenfassende Statistiken
    • best_total_free_days: Maximale zusammenhängende Freizeit
    • best_efficiency_percentage: Beste Effizienz ((freie Tage - Urlaubstage) / Urlaubstage × 100)
    • opportunities_found: Anzahl der gefundenen optimalen Fenster
  • optimal_windows: Liste der optimalen Urlaubsfenster (sortiert nach Effizienz)
    • rank: Position im Ranking (1 = bestes)
    • starts_on / ends_on: Zeitraum der zu nehmenden Urlaubstage
    • vacation_days_used: Verbrauchte Urlaubstage
    • total_free_days: Gesamtzahl zusammenhängender freier Tage
    • breakdown: Aufschlüsselung nach Tagestypen
      • vacation_days: Urlaubstage
      • weekend_days: Wochenendtage
      • holiday_days: Feiertage
    • efficiency_percentage: Effizienz dieses Fensters
    • spans_year_boundary: Ob das Fenster über den Jahreswechsel geht
    • includes_school_vacation: Ob Schulferien enthalten sind (relevant für budget-Variante)
    • related_holidays: Liste der enthaltenen Feiertage
  • cross_year_option: Optionales Jahreswechsel-Fenster (Dezember → Januar)
  • links: Hilfreiche Links
    • web_page: Link zur Web-Ansicht
    • icalendar: Link zum iCal-Download

iCal-Export

Der iCal-Endpunkt liefert eine Kalenderdatei mit den optimalen Urlaubsfenstern. Diese kann direkt in Kalender-Apps wie Google Calendar, Apple Calendar oder Outlook importiert werden.

Request 

GET https://www.mehr-schulferien.de/api/v2.1/federal-states/bayern/vacation-optimizer/icalendar?year=2026&days=10

Response: text/calendar Datei mit Content-Disposition: attachment Header.

Beispiel iCal-Inhalt 

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//mehr-schulferien.de//Urlaubsplaner//DE
X-WR-CALNAME:Urlaubsplaner Bayern 2026 (10 Tage)

BEGIN:VEVENT
DTSTART;VALUE=DATE:20260418
DTEND;VALUE=DATE:20260505
SUMMARY:Optimaler Urlaub (Rang 1) - 17 Tage
DESCRIPTION:10 Urlaubstage → 17 freie Tage (70% Effizienz)\n
  Enthält: Tag der Arbeit\n
  Berechnet von mehr-schulferien.de
URL:https://www.mehr-schulferien.de/urlaubsplaner/bayern/10-tage/2026
END:VEVENT

END:VCALENDAR

Tipp – Budget-Variante: Mit variant=budget werden nur Urlaubsfenster außerhalb der Schulferien berechnet. Diese Zeiträume sind oft günstiger für Reisen, da weniger Familien mit schulpflichtigen Kindern verreisen.

Hinweis – Effizienz-Berechnung: Die Effizienz gibt an, wie viele zusätzliche freie Tage pro Urlaubstag gewonnen werden. Eine Effizienz von 70% bedeutet: Mit 10 Urlaubstagen erreichen Sie 17 freie Tage (10 + 7 zusätzliche).

Fehler: Status 404 wird zurückgegeben, wenn das Bundesland nicht gefunden wird. Status 400 wird bei ungültigen Parametern zurückgegeben (z.B. days > 60 oder ungültiges Jahr).

Siehe auch