Next public holiday
Find one public holiday on or after a specified 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}/next?from_date={from_date}curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/next?from_date=2026-08-01" \
-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. |
from_date | date string | Required query value, YYYY-MM-DD, with a year from 1900 through 2200. No automatic today default. |
No region filter or pagination. MCP input objects reject extra fields.
Illustrative response
{
"country": "IDN",
"from_date": "2026-08-01",
"holiday": {
"date": "2026-08-17",
"name": "Independence Day",
"local_name": "Hari Kemerdekaan",
"subdivision_codes": [],
"nationwide": true,
"observed": null
}
}The start date is inclusive. Searches the current year, then the following year only if needed. Missing required coverage returns 503. Never searches past 2200; no remaining event in that maximum year returns holiday: null. Regional holidays can be returned. When several events share the earliest date, the first in the stable sort wins; use the date endpoint to get all of them.
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_next_holiday",
"arguments": {
"country": "IDN",
"from_date": "2026-08-01"
}
}
}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.