Holidays on a date
Retrieve every published public holiday on one local civil date.
Request · access not open
This contract is not live for customer keys. Examples show the request shape after availability opens.
GET /v1/calendars/holidays/{country}/on/{date}curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/on/2026-08-17" \
-H "Authorization: Bearer $NARWHAL_API_KEY"Required parameters
| Name | Type | Rule |
|---|---|---|
country | string | Required path value. One supported uppercase ISO alpha-3 code, such as IDN. |
date | date string | Required path value, YYYY-MM-DD, with a year from 1900 through 2200. |
No region filter or pagination. MCP input objects reject extra fields.
Illustrative response
{
"country": "IDN",
"date": "2026-08-17",
"holidays": [
{
"date": "2026-08-17",
"name": "Independence Day",
"local_name": "Hari Kemerdekaan",
"subdivision_codes": [],
"nationwide": true,
"observed": null
}
]
}Returns all matching events. An empty holidays array means no event matched within a complete published year; it does not prove that banks or exchanges are open. Missing year coverage returns 503.
Shared holiday fields. Every event has explicit national or regional applicability.
Matching MCP call
Send an authenticated POST /mcp with Accept: application/json, text/event-stream.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "calendars_get_holidays_on_date",
"arguments": {
"country": "IDN",
"date": "2026-08-17"
}
}
}Successful results have isError: false, the same response in structuredContent, and serialized JSON in content[0].text. Domain errors have isError: true.
Errors and quota
Invalid inputs return 400; missing or invalid keys return 401. Unmounted routes return 404. Rate or quota exhaustion returns 429. Missing, invalid or withdrawn calendars return 503 calendar_coverage_unavailable.
One successful call consumes one monthly request, regardless of event count or years read. Errors do not consume monthly quota. Shared error details.