List public holidays

Retrieve the complete published calendar for one country and year.

Request

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

GET /v1/calendars/holidays/{country}/{year}

curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026" \
  -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.
`year`	integer	Required path value, 1900–2200 inclusive. This range does not promise historical coverage.
`version_id`	UUID string	Optional query value from a holiday event’s resource_version. Reads that immutable country-year calendar while source rights remain available. Omit it to read the current calendar. An unknown version returns 404 calendar_not_published; a failed read returns 503.
`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 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. 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