Documentation

The Holiday API returns public holidays and observances by country and/or religion. 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). 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"
  }
]

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.