下一個公共假日

查找指定當地公曆日期當天或之後的一個公共假日。

請求

使用 Narwhal 密鑰即可存取已發布的國家-年份數據。檢查覆蓋範圍和作用域之後再請求日期。

GET /v1/calendars/holidays/{country}/next?from_date={from_date}

curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/next?from_date=2026-08-01" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

參數

名稱	類型	規則
`country`	字串	必填路徑值。一個受支援的大寫 ISO 三字母代碼，例如 IDN。
`from_date`	日期字串	必填查詢值，格式為 YYYY-MM-DD，年份範圍為 1900 至 2200。不自動預設為今天。
`scope`	字串	可選查詢篩選條件：national_public、regional_public、bank、federal_government、central_government、collective_leave、public_sector 或 private_sector。省略此項可返回所有已發布類別。

沒有細分地區篩選或分頁。MCP 輸入對象會拒絕額外欄位。

說明性回應

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

開始日期包含在內。介面先搜尋當前年份，僅在必要時搜尋下一年份。缺少必需覆蓋範圍時返回503。搜尋不會超過2200年；在這個最大年份沒有剩餘事件時返回holiday: null。可以返回地區假日。多個事件同屬最早日期時，穩定排序中的第一個勝出；使用日期端點獲取全部事件。

共享假日欄位。每個事件都明確標注適用於全國還是特定地區。

對應的 MCP 呼叫

發送經過身份驗證的 POST /mcp 與 Accept: application/json, text/event-stream.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calendars_get_next_holiday",
    "arguments": {
      "country": "IDN",
      "from_date": "2026-08-01"
    }
  }
}

成功的結果包含 isError: false，相同的回應位於 structuredContent，以及序列化後的 JSON，位於 content[0].text。領域錯誤包含 isError: true.

錯誤與配額

無效輸入返回 400；缺失或無效密鑰返回 401；未掛載路由返回 404；匯率或配額耗盡返回 429；缺失、無效或已撤回的日曆返回 503 calendar_coverage_unavailable.

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

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