Dokumentation

Die Holiday API liefert gesetzliche Feiertage und Gedenktage nach Land und/oder Religion. Der Business-Days-Endpunkt (GET /api/business-days) verwendet dieselbe API-Key-Authentifizierung. Alle Anfragen erfordern die Authentifizierung mit einem API-Key. Du kannst API-Keys in deinem Dashboard erstellen und verwalten. Der Free-Plan (Standard) verwendet dieselbe Basis-URL und denselben API-Key, damit du die Integration vor dem Livegang testen kannst.

Jedes verifizierte Konto startet im Free-Plan. Du kannst dieselben Endpunkte, Parameter und dieselbe Authentifizierung verwenden, um deine Integration zu entwickeln und zu testen. Wenn der Free-Plan nicht mehr ausreicht, kannst du im Dashboard upgraden.

Was gleich bleibt

Du erhältst Zugriff auf dieselbe Holiday API: dieselbe Basis-URL, GET /api/holidays und dieselben Query-Parameter (country, religion, from, to, lang, region, provisional, type, scope). GET /api/business-days ist ebenfalls verfügbar, mit derselben Authentifizierung, und das Response-Format ist identisch. So kannst du gegen die echte API entwickeln und testen, ohne beim Upgrade Code zu ändern.

Einschränkungen

• Monatliches Anfragekontingent: Der Free-Plan enthält eine feste Anzahl von Anfragen pro Kalendermonat. Wenn du das Kontingent erreichst, werden Anfragen bis zum nächsten Monat oder bis zu einem Upgrade blockiert.
• Funktionslimits: Der Free-Plan begrenzt API-Keys, Sprachen und den Zugriff auf Untereinheiten-Feiertage. Siehe Preise für alle Limits.
• Keine Übernutzung im Free-Plan: Der Free-Plan enthält keine kostenpflichtige Übernutzung. Upgrade, um nach Erreichen des Limits fortzufahren.

Für den vollständigen Ergebnissatz und produktionsreife Limits wähle einen Plan unter Preise oder gehe in deinem Dashboard zu Nutzung bzw. Abrechnung.

Sende deinen API-Key im Authorization-Header als Bearer-Token. Erstelle Schlüssel auf der Seite API-Keys in deinem Dashboard.

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/holidays?country=US"

Verwende https://api.holidaydb.com für alle API-Anfragen. Für CURL und serverseitige Integrationen musst du diese absolute URL verwenden.

Liefert Feiertage, gefiltert nach country und/oder religion. Mindestens einer von country oder religion ist erforderlich.

Query-Parameter

Response: JSON-Array von Feiertagsobjekten mit uuid, country_code, religion_slug, type, scope, region_codes, region_names, start_date, end_date, provisional, substitute, summary, language. Für Länderkalender (country_code nicht null) beschreiben type und scope territoriale Kategorien (gesetzlicher Feiertag vs. observance, national vs. subnational). Für religiöse Kalender (religion_slug nicht null und oft country_code null) können type und scope "unknown" sein und sollten nicht territorial interpretiert werden; verwende religion_slug (und Datumswerte), um mit diesen observances zu arbeiten. Ersatzfeiertage enthalten canonical_uuid. Verwende include=canonical, um den kanonischen Feiertag pro Ersatz einzubetten; verwende include=substitute, um ein substitutes-Array pro kanonischem Feiertag einzubetten.

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/holidays?country=US"

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "country_code": "US",
    "religion_slug": null,
    "type": "public_holiday",
    "scope": "national",
    "region_codes": [],
    "region_names": [],
    "start_date": "2026-07-04",
    "end_date": "2026-07-04",
    "provisional": false,
    "summary": "Independence Day",
    "language": "en"
  }
  // ... weitere Feiertagsobjekte in der vollständigen Antwort
]

Liefert, wie viele Arbeitstage in einem Kalendermonat oder ganzen Jahr für ein ISO-Land liegen. Standardmäßig gilt die westliche Arbeitswoche Montag bis Freitag (ISO-Wochentage 1,2,3,4,5); überschreibbar über weekdays. Standardmäßig werden nur nationale Feiertage ausgeschlossen. Mit optionalem region werden zusätzlich subnationale Feiertage ausgeschlossen, deren region_codes diesen ISO-3166-2-Code enthalten: dieselbe Regel wie bei GET /api/holidays?country=...&region=... (nationale Tage sind immer enthalten; region bedeutet nicht „nur Region“). Dieser Endpunkt erfordert denselben Bearer-API-Key und dieselben Token-Berechtigungen wie GET /api/holidays.

Subdivision-Filterung erfordert einen Plan mit Untereinheiten-Feiertagen (Pro/Full), wie bei der Holidays-API.

Query-Parameter

Response: JSON-Objekt mit country_code, region (normalisierter Code oder null), weekdays (Array der tatsächlich verwendeten Integer-Wochentage), year und month (beide null im Range-Modus), range (from-/to-Daten, immer das aufgelöste inklusive Fenster) und business_days (Integer-Anzahl). Wenn include 1 oder true ist, enthält die Antwort zusätzlich holidays: Feiertage, die in die Zählung eingingen (nur national bei fehlendem region; national plus passende subnationale bei gesetztem region), mit vollständigen Feldern wie im letzten Beispiel-Tab.

Wenn wir den Kalender dieses Landes noch nicht abdecken, liefert die API 404 mit error und country_code (nicht derselbe Body wie „Country not found“ bei GET /api/holidays).

Die ersten vier Beispiel-Tabs lassen include weg (kein holidays im Beispiel-JSON). Der letzte Tab zeigt include=1 mit holidays-Array.

Die Beispiele unten verwenden 2026. Die business_days-Werte wurden manuell gegen offizielle nationale Regeln geprüft: US-Bundesfeiertage (OPM); deutsche Feiertage, die an diesem Datum in allen Bundesländern gelten; kanadische bundesgesetzliche Feiertage (Juli 2026 hat nur Canada Day an einem Mittwoch). Feiertage am Wochenende reduzieren die Werktagsanzahl nicht. Live-API-Werte folgen den in HolidayDB gespeicherten Feiertagen und sollten bei gleichen Regeln übereinstimmen; wenn in unseren Daten ein Eintrag ergänzt oder korrigiert wird, können sich Zählungen leicht ändern.

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/business-days?country=US&year=2026&month=1"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "business_days": 20
}

Liefert, wie viele working minutes (plus eine praktische Stunden/Minuten-Aufschlüsselung) in einen Kalendermonat, ein volles Jahr oder einen inklusiven Datumsbereich für ein ISO-Land fallen. Es verwendet dieselben Wochentags- und Feiertagsregeln wie GET /api/business-days und multipliziert dann mit einer erforderlichen workday-Dauer.

Subdivision-Filterung (region) erfordert einen Plan mit Untereinheiten-Feiertagen (Pro/Full), wie bei der Holidays-API und business-days.

Query-Parameter

Response: JSON-Objekt mit denselben Basisfeldern wie business-days plus working_days, workday, workday_minutes, working_minutes und working_hours (Stunden/Minuten-Aufschlüsselung).

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/working-hours?country=US&year=2026&month=1&workday=08:00"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "working_days": 20,
  "workday": "08:00",
  "workday_minutes": 480,
  "working_minutes": 9600,
  "working_hours": {
    "hours": 160,
    "minutes": 0
  }
}

Proratisiert einen Gehaltsbetrag auf Basis von working days in einem ausgewählten Fenster innerhalb eines Abrechnungszeitraums. Working days werden als ausgewählte ISO-Wochentage (Standard Mo-Fr) minus Feiertage gezählt (und optional regionale Feiertage, wenn region verwendet wird).

Du kannst den Abrechnungszeitraum über den Kalendermodus (year/month) oder über explizite Daten (period_from/period_to) wählen. Optional kannst du ein benutzerdefiniertes Prorationsfenster (from/to) innerhalb dieses Zeitraums angeben; andernfalls ist das Fenster der gesamte Zeitraum.

Query-Parameter

Response: JSON-Objekt mit period_working_days, window_working_days, ratio, salary und prorated_salary. Verwende period für die Grenzen des Abrechnungszeitraums und range für das Prorationsfenster.

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/salary-proration?country=US&year=2026&month=1&salary=5000"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "period": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "period_working_days": 20,
  "window_working_days": 20,
  "ratio": "1.000000",
  "salary": "5000.00",
  "salary_scale": 2,
  "prorated_salary": "5000.00"
}

Berechnet angesammelten Urlaub, genommenen Urlaub (optional mit Urlaubsfenster) und Endsaldo für einen Berichtszeitraum. Arbeitszeit wird aus ausgewählten weekdays minus Feiertagen für das gewählte country und optional region abgeleitet.

Query-Parameter

Response: JSON-Objekt mit Zeitraumgrenzen, Arbeits-Summen und hybriden Saldenfeldern: accrued_hours/taken_hours/ending_balance_hours plus abgeleitete *_days-Werte.

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/leave-pto?country=US&year=2026&month=1&workday=08:00&accrual_hours_per_month=8"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "workday": "08:00",
  "workday_minutes": 480,
  "period": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "period_working_days": 21,
  "accrued_hours": "8.00",
  "taken_hours": "0.00",
  "ending_balance_hours": "8.00"
}

Berechnet ein Fälligkeitsdatum durch Hinzufügen von Arbeitstagen zu einem Startdatum, unter Ausschluss von Wochenenden und Feiertagen für das gewählte country und optionale region.

Query-Parameter

Erforderliche Parameter sind country, start und sla_business_days.

Response: JSON-Objekt mit deadline und zugehörigen Kontextfeldern (country/region, weekdays und Scan-Bereich).

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/sla-deadline?country=US&start=2026-01-02&sla_business_days=1"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "start": "2026-01-02",
  "sla_business_days": 1,
  "deadline": "2026-01-05"
}

Berechnet ein voraussichtliches Lieferdatum durch Hinzufügen von Arbeitstagen zu einem Startdatum, unter Ausschluss von Wochenenden und Feiertagen für das gewählte country und optionale region.

Query-Parameter

Erforderliche Parameter sind country, start und delivery_business_days.

Response: JSON-Objekt mit delivery_date und zugehörigen Kontextfeldern (country/region, weekdays und Scan-Bereich).

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/delivery-date?country=US&start=2026-01-02&delivery_business_days=3"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "start": "2026-01-02",
  "delivery_business_days": 3,
  "delivery_date": "2026-01-07"
}

Liefert „bridge day“-Möglichkeiten für ein country und year - kurze Folgen von Arbeitstagen zwischen arbeitsfreien Tagen, bei denen mindestens ein Nachbarblock einen Feiertag enthält. Jede Möglichkeit enthält den resultierenden zusammenhängenden Frei-Block und ein Effizienzverhältnis, damit du lange Wochenenden priorisieren kannst.

Query-Parameter

Erforderliche Parameter sind country und year.

Response: JSON-Objekt mit einem bridge_opportunities-Array, nach Effizienz absteigend sortiert. Jede Möglichkeit zeigt die zu nehmenden Arbeitstage, den resultierenden zusammenhängenden Frei-Block, die Anzahl freier Tage, das Effizienzverhältnis (freie Tage / Brückentage) und die Anker-Feiertage.

Beispiele

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/bridge-days?country=DE&year=2026"

{
  "country_code": "DE",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": null,
  "max_gap": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  },
  "bridge_opportunities": [
    {
      "bridge_days": [
        "2026-05-15"
      ],
      "bridge_days_count": 1,
      "off_block": {
        "from": "2026-05-14",
        "to": "2026-05-17"
      },
      "off_days_count": 4,
      "efficiency": 4,
      "anchor_holidays": [
        {
          "uuid": "...",
          "summary": "Christi Himmelfahrt",
          "start_date": "2026-05-14",
          "end_date": "2026-05-14"
        }
      ]
    }
  ]
}

Liefert die Liste der von HolidayDB unterstützten Sprachcodes für übersetzte Feiertagsnamen. Dieser Endpunkt ist für Pläne verfügbar, die mehrere Sprachen enthalten (Full). Wenn dein Plan nur Englisch enthält, gibt die API `403` zurück.

Query-Parameter

Keine.

Antwort

JSON-Objekt mit einem languages-Array. Jeder Eintrag enthält einen code (z. B. en, de, pt_BR, en_US) und einen name. Diese Codes werden an lang übergeben; siehe lang-Parameter zur Auflösung und zum Fallback bei Primary-Tags.

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/languages"

{
 "languages": [
 { "code": "en", "name": "English" },
 { "code": "de", "name": "German" }
 ]
}

Die Rechnerseiten auf dieser Website verwenden einen öffentlichen Helper-Endpunkt GET /api/tools/languages, um Sprach-Dropdowns ohne API-Key zu befüllen.

Error-Response-Body

Error-Responses sind JSON auf der authentifizierten Produkt-API (GET /api/holidays, Rechner-Endpunkte usw.).

Öffentliche /api/tools/*-Routen nutzen ein anderes Fehlerformat und sind hier nicht beschrieben.

{
  "error": "Unauthorized. Provide a valid API key in the Authorization header as Bearer token."
}

Der Parameter region (Untereinheiten-Feiertage) und der Parameter lang (mehrere Sprachen) erfordern Pro- oder Full-Pläne. Basic enthält nur nationale Feiertage auf Englisch. Siehe Preise oder deine Seiten Abrechnung und Nutzung für Details.