Documentation

The Holiday API returns public holidays and observances by country and/or religion. The Business days endpoint (GET /api/business-days) uses the same API key authentication. All requests require authentication with an API key. You can create and manage API keys in your dashboard. The Free plan (default) uses the same base URL and the same API key so you can test integration before going live.

Every verified account starts on the Free plan. You can use the same endpoints, parameters, and authentication to build and test your integration. When you outgrow the Free plan, upgrade in the dashboard.

What works the same

You get access to the same Holiday API: the same base URL,GET /api/holidays, and the same query parameters (country, religion,from, to, lang, region,provisional, type, scope). GET /api/business-days is also available with the same authentication and the response shape is identical, so you can develop and test your code against the real API without changing it when you upgrade.

Limitations

• Monthly request quota: The Free plan includes a fixed number of requests per calendar month. When you reach the quota, requests are blocked until the next month or until you upgrade.
• Feature limits: The Free plan limits API keys, languages, and subdivision-holiday access. See pricing for full limits.
• No overage on Free: The Free plan does not include paid overage. Upgrade to continue once you hit the limit.

To get the full result set and production-ready limits, choose a plan from pricing or go to Usage or Billing in your dashboard.

Send your API key in the Authorization header as a Bearer token. Create keys on the API Keys page in your dashboard.

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

Use https://api.holidaydb.com for all API requests. For CURL and server-side integrations you must use this absolute URL.

Returns holidays filtered by country and/or religion. At least one of country or religion is required.

Query parameters

Response: JSON array of holiday objects with uuid, country_code, religion_slug, type, scope, region_codes, region_names, start_date, end_date, provisional, substitute, summary, language. For country calendars (country_code not null), type and scope describe territorial categories (public holiday vs observance, national vs subnational). For religious calendars (religion_slug not null and often country_code null), type and scope may be "unknown" and should not be interpreted as territorial; use religion_slug (and dates) to work with those observances. Substitute holidays include canonical_uuid. Use include=canonical to embed the canonical holiday for each substitute; use include=substitute to embed a substitutes array for each canonical.

Examples

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"
  }
  // ... more holiday objects in the full response
]

Returns how many working days fall in a calendar month or full year for one ISO country. By default the working week is Western Monday to Friday (ISO weekdays 1,2,3,4,5); override with optional weekdays. By default only national public holidays are excluded. With optional region, the count also excludes subnational public holidays whose region_codes include that ISO 3166-2 code: the same rule as GET /api/holidays?country=...&region=... (national days are always included; region does not mean “region-only”). This endpoint requires the same Bearer API key and token abilities as GET /api/holidays.

Subdivision filtering requires a plan that includes subdivision holidays (Pro/Full), same as the holidays API.

Query parameters

Response: JSON object with country_code, region (normalized code or null), weekdays (array of integers actually used for the count), year and month (both null in range mode), range (from, to dates, always the resolved inclusive window), and business_days (integer count). When include is 1 or true, the response also has holidays: public holidays that fed the count (national only when region is omitted; national plus matching subnational when region is set), with full fields as in the last example tab.

If we do not yet cover that country's calendar, the API returns 404 with code: "country_not_supported" and an error message (not the same body as "Country not found" on GET /api/holidays).

The first four example tabs omit include (no holidays in the sample JSON). The last tab shows include=1 with a holidays array.

The examples below use 2026. The business_days numbers were checked manually against official national rules: US federal holidays (OPM); German holidays observed in all states on that date; Canada federal statutory holidays (July 2026 has Canada Day on a Wednesday only). Weekend-fixed holidays do not reduce the weekday count. Live API values follow HolidayDB's stored holidays and should match for the same rules; if a row is added or corrected in our data, counts can change slightly.

Examples

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
}

Returns how many working minutes (and a convenience hours/minutes breakdown) fall in a calendar month, full year, or inclusive date range for one ISO country. It uses the same weekday and public-holiday rules as GET /api/business-days, then multiplies by a required workday duration.

Subdivision filtering (region) requires a plan that includes subdivision holidays (Pro/Full), same as the holidays API and business-days.

Query parameters

Response: JSON object with the same base fields as business-days plus working_days, workday, workday_minutes, working_minutes, and working_hours (hours/minutes breakdown).

Examples

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 }
}

Prorates a salary amount based on working days in a selected window inside a payroll period. Working days are counted as selected ISO weekdays (default Mon-Fri) minus public holidays (and optional regional holidays when region is used).

You can choose the payroll period via calendar mode (year/month) or via explicit dates (period_from/period_to). Optionally, provide a custom proration window (from/to) inside that payroll period; otherwise the window is the full payroll period.

Query parameters

Response: JSON object with period_working_days, window_working_days, ratio, salary, and prorated_salary. Use period for the payroll period bounds and range for the proration window.

Examples

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"
}

Calculates accrued leave, taken leave (optional leave window), and ending balance for a reporting period. Working time is derived from selected weekdays minus public holidays for the selected country and optional region.

Query parameters

Response: JSON object with period bounds, working totals, and hybrid balance fields: accrued_hours/taken_hours/ending_balance_hours plus derived *_days values.

Examples

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"
}

Calculates a due date by adding business days to a start date, excluding weekends and public holidays for the selected country and optional region.

Query parameters

Required parameters are country, start, and sla_business_days.

Response: JSON object with deadline and related context fields (country/region, weekdays, and scan range).

Examples

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"
}

Calculates an estimated delivery date by adding business days to a start date, excluding weekends and public holidays for the selected country and optional region.

Query parameters

Required parameters are country, start, and delivery_business_days.

Response: JSON object with delivery_date and related context fields (country/region, weekdays, and scan range).

Examples

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"
}

Returns "bridge day" opportunities for a country and year - short runs of working days sandwiched between non-working days where at least one neighbor block contains a public holiday. Each opportunity includes the resulting consecutive off-block and an efficiency ratio so you can rank long-weekend plays.

Query parameters

Required parameters are country and year.

Response: JSON object with a bridge_opportunities array sorted by efficiency descending. Each opportunity exposes the working days that need to be taken off, the resulting consecutive off-block, the off-day count, the efficiency ratio (off-days / bridge days), and the anchor holidays.

Examples

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"
        }
      ]
    }
  ]
}

Returns the list of language codes supported by HolidayDB for translated holiday names. This endpoint is available for plans that include multiple languages (Full). If your plan only includes English, the API returns 403.

Query parameters

None.

Response

JSON object with a languages array. Each item contains a language code (ISO 639-1) and a display name.

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

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

Calculator pages on this site use a public helper endpoint GET /api/tools/languages to populate language dropdowns without requiring an API key.

Error response body

Error responses are JSON. Authentication/validation errors include an error string (and validation errors also include errors). Other errors may use diagnostic fields like id/status/code/title/detail.

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

The region parameter (subdivision holidays) and the lang parameter (multiple languages) require Pro or Full plans. Basic includes national holidays in English only. See pricing or your Billing and Usage pages for details.