Holidays on a date

Retrieve every published public holiday on one 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}/on/{date}

curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/on/2026-08-17" \
  -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.
`date`	date string	Required path value, YYYY-MM-DD, with a year from 1900 through 2200.
`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": []
    }
  ],
  "holidays": [
    {
      "date": "2026-08-17",
      "name": "Independence Day",
      "local_name": "Proklamasi Kemerdekaan",
      "subdivision_codes": [],
      "scope": "national_public"
    }
  ]
}

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. An unpublished country-year returns 404 calendar_not_published; a failed read 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. 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