文件
下一個國定假日
尋找指定當地曆日當天或之後的一個國定假日。
請求
使用 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。
每次成功呼叫消耗一次月度請求配額，與讀取的事件數量或年份無關。錯誤不會消耗月度配額。 共享錯誤詳情。