Calendars API reference
Yearly public holidays, date lookups and next-holiday requests through REST and MCP.
Access not open
These are pre-release contracts. Calendar endpoints are not available to customer keys and do not appear in the live OpenAPI catalogue yet. The examples are illustrative.
Three operations
| Reference | GET endpoint | MCP tool |
|---|---|---|
| List public holidays | /v1/calendars/holidays/{country}/{year} | calendars_list_holidays |
| Holidays on a date | /v1/calendars/holidays/{country}/on/{date} | calendars_get_holidays_on_date |
| Next public holiday | /v1/calendars/holidays/{country}/next?from_date={from_date} | calendars_get_next_holiday |
Use uppercase country codes such as IDN and local civil dates in YYYY-MM-DD form. Every parameter shown is required. There is no pagination or region filter.
Shared holiday object
| Field | Type | Meaning |
|---|---|---|
date | date string | Local calendar date, not an ingestion timestamp. |
name | string | English/display name, 1–256 characters. |
local_name | string or null | Local name when available, 1–256 characters. |
subdivision_codes | string array | Unique sorted codes such as GB-SCT, belonging to the country. |
nationwide | boolean | True requires an empty subdivision list; false requires a nonempty list. |
observed | boolean or null | Explicit observed/substitute status. Null means unknown, not false. |
Normal responses include all six fields. Request IDs and quota remain in headers. Source URLs and ingestion check times are not included in success bodies.
Coverage and limits
The nineteen-country target uses these ISO alpha-3 codes:
ARG, AUS, BRA, CAN, CHN, FRA, DEU, IND, IDN, ITA, JPN, MEX, KOR, RUS, SAU, ZAF, TUR, GBR, USA
Year validation permits 1900–2200; that is not a claim of historical coverage. Initial source review targets published 2026 and 2027 calendars. China, India and Saudi Arabia require particular source and scope review.
A published year contains 1–400 events. Missing or withdrawn coverage returns 503 calendar_coverage_unavailable. A successful date lookup can return an empty array only when its year is published. Public holidays do not prove bank or exchange closure.
Successful calls consume one shared monthly request, including empty date results. Errors do not consume monthly quota; short-window rate limiting still applies. Read the shared errors and quota contract.