列出國定假日

取得一個國家和年份的完整已發布行事曆。

請求

使用 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。

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

所有行事曆操作 · 涵蓋範圍與解讀