Public Holidays API

The API provides public-holiday data for over 100 countries. You can retrieve the complete, authoritative list at any time by calling the /holidays/v1/countries endpoint, which returns each supported country's ISO-3166 alpha-2 code and English name. This is the recommended way to validate a country before making other requests and to populate country dropdowns in your application.

Use the /holidays/v1/is-holiday endpoint with a country code and a date in YYYY-MM-DD form, for example /holidays/v1/is-holiday?country=US&date=2026-07-03. The response includes an is_holiday boolean and a holiday object containing the full matching record (local name, English name, type flags, and regional applicability). When the date is an ordinary day, is_holiday is false and the holiday field is null, which makes it easy to implement business-day and conditional-workflow logic.

The /holidays/v1/public endpoint returns all holidays for a single calendar year (2000-2100). The /holidays/v1/range endpoint returns holidays within an inclusive from/to window sorted ascending, and the window may span at most 5 years. The /holidays/v1/next endpoint returns the upcoming holidays in the next 365 days. Choose public for full-year calendars, range for arbitrary windows, and next for dashboards and reminders.

Each holiday object includes a global boolean and a counties field. When global is true the holiday applies nationwide and counties is null. When global is false the holiday applies only to the subdivisions listed in counties, which contains ISO-3166-2 codes. Always branch on these fields when regional accuracy matters so that a holiday observed in only one region doesn't incorrectly affect nationwide logic.

Authentication uses a single API key. Pass it as a query parameter, ?apikey=YOUR_API_KEY, or send it in an X-Api-Key header. There is no OAuth flow, no SDK, and no webhooks to configure: just add your key and call. The same key works across every API Codex API.

Inputs are validated before any data is fetched, so bad requests fail fast with a clean 400 and a human-readable message, such as an invalid country code, an out-of-range year, a malformed date, or a 'from' date that is after the 'to' date. If the upstream holiday provider is unavailable, the API returns a tidy 502 with a detail field instead of leaking internal errors. Because responses are edge-cached, these upstream issues are rarely visible to end users, and a short retry with backoff handles transient failures gracefully.

Yes. The public, range, next, and countries endpoints accept an optional limit query parameter between 1 and 1000, defaulting to 50. This is useful for previews, paginated UIs, and reducing payload size when you only need the first few results — for example fetching just the next two upcoming holidays for a compact widget.