Endpoints
| Endpoint | Returns |
|---|
GET /api/holidays/{cc}/{year} | Full calendar: every holiday with date, name, weekday |
GET /api/holidays/next/{cc} | The next upcoming holiday with a days-away count |
GET /api/holidays/check/{cc}/{date} | Whether that date is a holiday or weekend, and if banks are closed |
| Auth | None, no API key required |
| Rate limit | 500 requests / day / IP, 30 / minute (see X-RateLimit-Remaining) |
| CORS | Access-Control-Allow-Origin: * |
| Coverage | 150+ countries, previous year through two years ahead |
Examples
| Calendar | curl https://bankholidaycheck.com/api/holidays/US/2027 |
| Next holiday | curl https://bankholidaycheck.com/api/holidays/next/GB |
| Date check | curl https://bankholidaycheck.com/api/holidays/check/DE/2027-10-03 |
| JavaScript | const r = await fetch('https://bankholidaycheck.com/api/holidays/next/US').then(r => r.json()); |
Response Shape (date check)
| Field | Type | Description |
|---|
data.is_holiday | boolean | Whether the date is a nationwide holiday |
data.holiday_name | string|null | The holiday's name when it is one |
data.is_weekend / data.weekday | boolean / string | Weekend detection and day name |
data.banks_closed | boolean | The practical answer: holiday or weekend |
Errors use standard codes: 400 bad country or date, 404 year not in dataset, 429 rate limited.
Fair Use & Attribution
- 500 requests per day per IP; responses cache for an hour, so cache on your side too.
- Dates are generated with the python-holidays library (MIT); a link back to bankholidaycheck.com is appreciated but not required.
- For contractual deadlines, verify critical dates with official government sources.