Calendar methodology and coverage
How to interpret public holiday dates, regional applicability and country-year availability.
Public holidays, not guaranteed closures
Access is not open. The calendar contract describes public holiday events on local civil dates. It does not determine bank opening hours, exchange sessions, settlement dates or whether a particular employer closes.
National events have nationwide: true. Regional events name their subdivisions. Observed/substitute status is explicit source metadata: null means unknown. The next-holiday lookup can return a regional event.
Nineteen-country target
ARG, AUS, BRA, CAN, CHN, FRA, DEU, IND, IDN, ITA, JPN, MEX, KOR, RUS, SAU, ZAF, TUR, GBR, USA
This is the sovereign G20 cohort; Singapore is not included. Each country-year must be reviewed before publication. Structural support for nineteen codes does not mean nineteen approved calendars. The 1900–2200 input range is a validation boundary, not historical coverage.
Source review before access opens
The initial plan uses Nager.Date for sixteen countries and reviewed official documents for China, India and Saudi Arabia. Seventeen 2026 provider responses have passed structural checks; official completeness and source permissions remain under review. No 2027 cohort has been approved.
- China publishes holiday breaks and make-up working days. A short list of festival dates is not the full arrangement; working-day calculations are outside this API.
- India has central-government and state-specific calendars. A central-office schedule must not be presented as universal closure.
- Saudi public-sector and financial-institution schedules differ. Financial calendars cannot stand in for public holidays.
- Indonesia’s national holidays and collective leave are distinct concepts. Holiday dates must not silently imply collective leave.
Updates and missing coverage
Calendars change when source publications change, not when the clock reaches a new day. Planned daily checks detect changes; a recent check alone does not prove complete or current dates.
Publication requires a complete validated country-year. A failed refresh preserves the previous approved version; revoked approval prevents it from being served. Missing required coverage returns 503. Reviewed documents that change require another review before their dates can be replaced.
The yearly endpoint lists all published events. The date endpoint can return no matches within a published year. The next endpoint searches the requested year and, only when needed, the following year. It does not guess unpublished dates.