列出公共假日

獲取一個國家和年份的完整已發布日曆。

請求

使用 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（含首尾）。此範圍不保證歷史覆蓋。
`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.

每次成功呼叫消耗一次月度請求額度，與讀取的事件數量或年份無關。錯誤不會消耗月度額度。共享錯誤詳情.

所有日曆操作 · 覆蓋範圍和解讀