Next public holiday

Find one public holiday on or after a specified local civil date.

Request

Available for published country-years with your Narwhal key. Check coverage and scope before requesting a date.

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"

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.
`scope`	string	Optional query filter: national_public, regional_public, bank, federal_government, central_government, collective_leave, public_sector or private_sector. Omit it to return all published categories. A scope with no published coverage for the country-year returns 404 calendar_not_published; the response coverage lists only that scope.

No subdivision filter or pagination. MCP input objects reject extra fields.

Illustrative response

{
  "country": "IDN",
  "coverage": [
    {
      "scope": "collective_leave",
      "subdivision_codes": []
    },
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holiday": {
    "date": "2026-08-17",
    "name": "Independence Day",
    "local_name": "Proklamasi Kemerdekaan",
    "subdivision_codes": [],
    "scope": "national_public"
  }
}

The start date is inclusive. Searches the current year, then the following year only if needed. If a year it has to read is not published, it returns 404 calendar_not_published; a failed read 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. An unpublished country-year calendar returns 404 calendar_not_published; a calendar that cannot be served safely right now returns 503 calendar_coverage_unavailable.

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).

One successful call consumes one monthly request, regardless of event count or years read. Errors do not consume monthly quota. Shared error details.

All calendar operations · Coverage and interpretation