Three useful lookups
Annotate reports, show upcoming holidays, and add local date context to an agent's answer.
Read the methodology →All APIs
Public Holiday Calendar API
Published public holidays by country, year, and date.
First request
Quickstart →curl --request GET \
--url "https://api.narwhalapi.com/v1/calendars/holidays/IDN/next?from_date=2026-08-01" \
--header "Authorization: Bearer $NARWHAL_API_KEY"Example response Illustrative response · not a live request
{
"country": "IDN",
"from_date": "2026-08-01",
"coverage": [
{
"scope": "national_public",
"nationwide": true,
"subdivision_codes": []
},
{
"scope": "collective_leave",
"nationwide": true,
"subdivision_codes": []
}
],
"holiday": {
"date": "2026-08-17",
"name": "Independence Day",
"local_name": "Hari Kemerdekaan",
"subdivision_codes": [],
"nationwide": true,
"observed": null,
"scope": "national_public"
}
}Endpoints
GETList a published year/v1/calendars/holidays/{country}/{year}
GETCheck a date/v1/calendars/holidays/{country}/on/{date}
GETFind the next holiday/v1/calendars/holidays/{country}/next
Sources and methodology
National and regional scope
Know whether an event applies nationwide or only to the named subdivisions.
Coverage you can check
Published years and their exact scope are listed in the calendar reference. Other countries and years remain explicitly unavailable as the nineteen-country target expands.
Coverage
View coverage →Public holidays do not establish bank, exchange or settlement closure. Regional events remain visible, observed status can be unknown, and missing calendar coverage returns an error rather than a guessed date.