Public Holidays API reference

Live public beta

Use your Narwhal API key for the published country-years below. REST and MCP share the same coverage and quota. Missing coverage returns an explicit error; the examples remain illustrative.

Public Holidays product overview · Methodology and source review

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. The country and date/year parameters are required. An optional scope filter selects a holiday category. There is no pagination or subdivision 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	Local name when available, 1–256 characters. Left out when not available.
`subdivision_codes`	string array	Unique, sorted codes for subdivisions of the country, such as GB-SCT. An empty array means nationwide.
`scope`	string	Holiday category, such as national_public, bank, federal_government or collective_leave.
`observed`	boolean	Explicit observed/substitute status. Left out when unknown. Unknown does not mean false.

Holiday objects always include date, name, scope and subdivision_codes. Each response also includes coverage declarations with scope and subdivision_codes, including for an empty date result. Request IDs and quota remain in headers. Source URLs and ingestion check times are not included in success bodies.

Coverage and limits

Published API coverage · countries and years not listed as available return coverage unavailable.
Country	2026	2027	Published scope
`ARG`	Available	Not available yet	National public holidays
`AUS`	Available	Available	New South Wales only: regional public and bank holidays
`AUT`	Available	Available	National public holidays
`BEL`	Available	Available	National public holidays
`BRA`	Available	Not available yet	Federal-government public holidays; optional and partial closures excluded
`CAN`	Available	Available	Nationwide statutory baseline for federally regulated private-sector employers; provincial and federal public-service calendars excluded
`CHN`	Available	Not available yet	National holiday breaks; make-up working days excluded
`COL`	Available	Available	National public holidays
`CZE`	Available	Available	National public holidays; significant days, ordinary Sundays and employer closures excluded
`DEU`	Available	Not available yet	Common nationwide public holidays; state additions excluded
`DNK`	Available	Available	Danmarks Nationalbank closing days; not a general employment holiday calendar
`ESP`	Available	Not available yet	National public holidays
`EST`	Available	Available	National public holidays and days of rest; national days of importance and shortened workdays excluded
`FRA`	Available	Available	Common national statutory holidays; regional additions excluded
`GBR`	Available	Available	Bank holidays for England and Wales, Scotland, and Northern Ireland
`HKG`	Available	Available	Hong Kong general holidays; ordinary Sundays excluded
`HRV`	Available	Available	National public holidays and non-working days; commemorations and denominational days excluded
`IDN`	Available	Available	National holidays and collective leave, separately labeled
`IND`	Not available yet	Not available yet	Source review in progress
`IRL`	Available	Available	National public holidays; employer-specific alternatives and leave entitlements excluded
`ITA`	Available	Available	National civil public holidays; regional and employer closures excluded
`JPN`	Available	Available	National public holidays
`KOR`	Not available yet	Not available yet	Source review in progress
`LTU`	Available	Available	National public holidays under Labour Code Article 123; regional events excluded
`LUX`	Available	Available	National public holidays
`LVA`	Available	Available	National public holidays; commemorations and regional events excluded
`MEX`	Available	Available	National mandatory labour-rest dates; banking, state/municipal-only and sector closures excluded
`NLD`	Available	Available	National public holidays; time off depends on employment terms
`NOR`	Available	Not available yet	Norges Bank settlement-system closing days; not a general employment holiday calendar
`NZL`	Available	Available	National holidays and observed dates; regional anniversaries excluded
`PHL`	Not available yet	Not available yet	Source review in progress
`POL`	Available	Available	National public holidays; ordinary Sundays, regional events and employer closures excluded
`PRT`	Available	Available	National mandatory public holidays; optional, municipal and regional holidays excluded
`RUS`	Not available yet	Not available yet	Source review in progress
`SAU`	Not available yet	Not available yet	Source review in progress
`SGP`	Available	Available	National public holidays and source-designated observed dates
`SVK`	Available	Available	National public holidays
`SVN`	Available	Available	National public holidays and work-free days; non-work-free commemorations and local holidays excluded
`SWE`	Available	Available	National public holidays
`TUR`	Not available yet	Not available yet	Source review in progress
`TWN`	Available	Available	Government office calendar; private-sector and market closures excluded
`USA`	Available	Available	Federal employee holidays and observed dates; state holidays excluded
`ZAF`	Available	Available	National public holidays; school-only holidays excluded

Available entries describe only the stated scope, not every local or sector holiday. Year validation permits 1900–2200; that is not a claim of historical coverage.

A published year contains 1–400 events. An unpublished country-year calendar returns 404 calendar_not_published; a calendar that cannot be served safely right now 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.

403 plan_upgrade_required when the year, date or range is before your plan's history window (Free 12 months, Basic 5 years, Pro full).

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.