Documentation
Three endpoint families, all live, all read-only, none of them behind a key.
v1 liveEndpoints
| Method and path | Returns |
|---|---|
GET /v1/holidays/{CC}/2026.json | Public holidays for one country in 2026. Query form: /v1/holidays?country=US&year=2026. |
GET /v1/business-days?country=&from=&to= | Business-day count for a range, with weekend days and holidays in range broken out. |
GET /v1/is-business-day?country=&date= | One date, one country, true or false plus the reason. |
GET /v1/countries.json and /v1/status.json | Coverage list with sources, and service status with dataset year. |
Conventions
- Dates use ISO 8601, YYYY-MM-DD. No times and no time zones in v1.
- Country codes are ISO 3166-1 alpha-2, uppercase.
- A holiday that falls on a weekend stays in the holiday list. The business-day endpoints decide what it does to a count.
- Observed and substitute days are their own entries, dated on the day they are observed.
No authentication in v1. The dataset is small and static, so keys would add friction without protecting anything scarce. If usage grows past what a static dataset should carry, keys arrive with the paid tiers and v1 keeps answering.
Error codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_parameter | A parameter is missing or malformed, for example a date that is not YYYY-MM-DD. |
| 404 | country_not_found | The country code is not in the covered set of 12. |
| 404 | year_not_covered | Only 2026 is in the dataset. Other years return this error instead of a guess. |
Errors use one shape: {"error": {"code": "...", "message": "..."}}. Try the bad-country button in the console to see one.