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. Development Mode (free) uses the same base URL and the same API key (create one in your dashboard when you have no paid plan) so you can test integration before going live.

If you have an account but no active paid subscription, your API requests run in Development mode. You can use the same endpoints, parameters, and authentication to build and test your integration. Development mode is intended for evaluation only; it is not suitable for production use.

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 dev-mode behavior. The response shape is identical, so you can develop and test your code against the real API without changing it when you upgrade.

Limitations

• Subset of results only: The API does not return the full set of holidays. Results are filtered server-side (e.g. only a fraction of matching holidays are included). You will see a smaller list than you would on a paid plan, but the structure and fields of each holiday are the same. This lets you verify your integration without exposing the complete dataset.
• Response header: When running in Development mode, the API adds the header X-Dev-Mode: true to every response. You can use this in your application to detect dev mode (e.g. for logging or to show a warning in a test environment).
• One API key only: You can create and use only one API key in Development mode. Paid plans allow more keys (see pricing).
• Not for production: Development mode is not intended for production traffic. Data completeness, rate limits, and availability may differ from paid plans. For production use, subscribe to Basic, Pro, or Full from Billing.

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

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
}

Error response body

All error responses are JSON with a single error key containing the message.

{
  "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.