List public holidays
Retrieve the complete published calendar for one country and year.
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}/{year}curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026" \
-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. |
year | integer | Required path value, 1900–2200 inclusive. This range does not promise historical coverage. |
No region filter or pagination. MCP input objects reject extra fields.
Illustrative response
{
"country": "IDN",
"year": 2026,
"holidays": [
{
"date": "2026-08-17",
"name": "Independence Day",
"local_name": "Hari Kemerdekaan",
"subdivision_codes": [],
"nationwide": true,
"observed": null
}
]
}Returns the full published year, ordered by date and name with stable tie-breaking. Distinct holidays on the same day remain separate. There is no pagination. The example shows one event, not a complete calendar.
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_list_holidays",
"arguments": {
"country": "IDN",
"year": 2026
}
}
}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.