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 |
GET /api/business-days/{cc}/{from}/{to} | Business-day count between two dates (YYYY-MM-DD, inclusive), excluding weekends and holidays |
| Auth | None required for the free per-IP allowance. An IPNOVA API key (free account at api.ipnova.com) applies your plan allowance instead: send it as the X-Api-Key header or the ?key= query parameter. Keyed responses carry X-Credits-Remaining and X-Credits-Used. |
| Rate limit | 100 requests a day and 30 a minute, per IP (see X-RateLimit-Remaining) |
| CORS | Access-Control-Allow-Origin: * |
| Coverage | 150+ countries, previous year through two years ahead |
| Language | lang query parameter, one of en (default), es, fr, de, pt, it, nl, pl; localizes holiday names in the response |
Plans
One key. Twelve APIs.
A free IPNOVA API account gives you 5,000 lookups a month across every API below, 60 a minute, no card, for evaluation and small projects. Paid plans from $19 a month for production volumes, with a commercial licence and a hard cap instead of overage billing.
Card BINVINSWIFT/BICIBANHS tariffDisposable emailIP dataPhoneHolidaysMAC vendorPostal codeAirport
Create your free key
Takes a minute. Send it as X-Api-Key or ?key=.
Without a key this API answers 100 requests a day per IP address, for evaluation and personal use. Try it: curl https://bankholidaycheck.com/api/holidays/US/2027
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 |
| Business days | curl https://bankholidaycheck.com/api/business-days/DE/2026-01-01/2026-01-31 |
| 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
Every non-200 response uses the same envelope: success: false, an error flag, a machine-readable reason, a human message, and a docs link back to this page.
| Status | Reason | Meaning |
|---|---|---|
400 | invalid_input | Bad country code or date |
401 | invalid_key | The supplied API key is unknown or revoked |
404 | not_found | Year not in the dataset |
404 | unknown_endpoint | Path under /api/ does not match a published endpoint |
429 | rate_limit | Too many requests in the last minute (Retry-After: 60) |
429 | daily_limit | Keyless per-IP daily cap reached |
429 | credits_exhausted | Keyed monthly allowance used up |
Example, a year not in the dataset:
{"success": false, "error": true, "reason": "not_found", "message": "Year not in the covered range.", "docs": "https://bankholidaycheck.com/holiday-api"}Response Shape (business days)
| Field | Type | Description |
|---|---|---|
from / to | string | The requested range, normalized to YYYY-MM-DD, inclusive |
data.business_days | int | Days in range that are neither a weekend nor a national holiday |
data.total_days | int | Total calendar days in the range |
data.weekend_days | int | Weekend days in the range |
data.holidays_skipped | array | National holidays in the range, each with date and name |
data.weekend | string | Which days count as the weekend for this country (e.g. "Sat-Sun weekend") |
Example response for GET /api/business-days/DE/2026-01-01/2026-01-31:
{"success":true,"country":"Germany","country_code":"DE","from":"2026-01-01","to":"2026-01-31","inclusive":true,"data":{"business_days":21,"total_days":31,"weekend_days":9,"holidays_skipped":[{"date":"2026-01-01","name":"New Year's Day"}],"weekend":"Sat-Sun weekend"},"page":"https://bankholidaycheck.com/business-days-calculator","attribution":"Data by BankHolidayCheck.com - generated with the python-holidays library (MIT).","docs":"https://bankholidaycheck.com/holiday-api"}Fair Use & Attribution
- 100 requests per day per IP; responses cache for an hour, so cache on your side too.
- For contractual deadlines, verify critical dates with official government sources.