列出节假日

获取一个国家和年份的完整已发布日历。

请求

使用 Narwhal 密钥即可访问已发布的国家-年份数据。检查覆盖范围和适用范围，然后再按日期查询。

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

curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

参数

名称	类型	规则
`country`	字符串	必填路径值。一个受支持的大写 ISO 三字母代码，例如 IDN。
`year`	整数	必填路径值，范围为1900至2200（含首尾）。此范围不保证历史覆盖。
`version_id`	UUID 字符串	可选查询值，取自假日事件的 resource_version。在来源数据的使用权仍然有效时，读取对应的不可变国家-年份日历。省略此值则读取当前日历。不可用的版本返回 503。
`scope`	字符串	可选查询筛选条件：national_public、regional_public、bank、federal_government、central_government、collective_leave、public_sector 或 private_sector。省略此项可返回所有已发布类别。

没有细分地区筛选或分页。MCP 输入对象会拒绝额外字段。

示例响应

{
  "country": "IDN",
  "year": 2026,
  "coverage": [
    {
      "scope": "national_public",
      "nationwide": true,
      "subdivision_codes": []
    },
    {
      "scope": "collective_leave",
      "nationwide": true,
      "subdivision_codes": []
    }
  ],
  "holidays": [
    {
      "date": "2026-08-17",
      "name": "Independence Day",
      "local_name": "Hari Kemerdekaan",
      "subdivision_codes": [],
      "nationwide": true,
      "observed": null,
      "scope": "national_public"
    }
  ]
}

返回完整发布年份，按日期和名称排序并稳定处理同值。当天不同节假日保持独立，不使用分页。示例仅展示一个事件，不是完整日历。

共享假日字段。每个事件都明确标注适用于全国还是特定地区。

对应的 MCP 调用

发送经过身份验证的 POST /mcp 与 Accept: application/json, text/event-stream。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calendars_list_holidays",
    "arguments": {
      "country": "IDN",
      "year": 2026
    }
  }
}

成功的结果包含 isError: false，相同的响应位于 structuredContent，序列化后的 JSON 位于 content[0].text。领域错误包含 isError: true。

错误与配额

无效输入返回 400；缺失或无效的密钥返回 401；未挂载的路由返回 404；请求频率超限或配额耗尽返回 429；缺失、无效或已撤回的日历返回 503 calendar_coverage_unavailable。

每次成功调用消耗一次月度请求配额，与读取的事件数量或年份数量无关。错误不会消耗月度配额。共享错误详情。

所有日历操作 · 覆盖范围和解读