日曆 API 參考
透過 REST 和 MCP 提供年度公共假日、日期查詢及下一個假日請求。
公開測試版已上線
使用你的 Narwhal API 密鑰存取下面已發布的國家-年份。REST 和 MCP 共享相同的覆蓋範圍和額度。缺失覆蓋範圍會返回明確錯誤；示例仍僅用於說明。
三個操作
| 參考 | GET 端點 | MCP 工具 |
|---|---|---|
| 列出公共假日 | /v1/calendars/holidays/{country}/{year} | calendars_list_holidays |
| 指定日期的假日 | /v1/calendars/holidays/{country}/on/{date} | calendars_get_holidays_on_date |
| 下一個公共假日 | /v1/calendars/holidays/{country}/next?from_date={from_date} | calendars_get_next_holiday |
使用大寫國家代碼，例如 IDN 以及當地公曆日期，位於 YYYY-MM-DD 表單。國家和日期/年份參數為必填項。可選的範圍篩選器用於選擇假日類別。此介面沒有分頁或細分地區篩選器。
共享假日對象
| 欄位 | 類型 | 含義 |
|---|---|---|
date | 日期字串 | 當地日曆日期，而不是數據攝取時間戳記。 |
name | 字串 | 英文或顯示名稱，長度為 1–256 個字元。 |
local_name | 字串或 null | 如有當地名稱則使用當地名稱，長度為 1–256 個字元。 |
subdivision_codes | 字串陣列 | 屬於該國家的唯一排序代碼，例如 GB-SCT。 |
nationwide | 布爾值 | true 要求細分地區列表為空；false 要求列表非空。 |
scope | 字串 | 假日類別，例如 national_public、bank、federal_government 或 collective_leave。 |
observed | 布爾值或null | 明確的 observed/substitute 狀態。Null 表示未知，不表示 false。 |
普通假日對象包含全部七個欄位。每個回應還包含覆蓋聲明，其中有 scope、nationwide 和 subdivision_codes，即使日期查詢結果為空也會包含。請求 ID 和配額仍保留在標頭中。成功回應正文不包含來源 URL 和數據攝取檢查時間。
覆蓋範圍和限制
| 國家 | 2026 | 2027 | 已發布的官方數據和文件說明來源、範圍、期間與限制。 |
|---|---|---|---|
ARG | 尚不可用 | 尚不可用 | 來源審查進行中 |
AUS | 可用 | 可用 | 僅限新南威爾士州：區域公共假日和銀行假日 |
BRA | 尚不可用 | 尚不可用 | 來源審查進行中 |
CAN | 尚不可用 | 尚不可用 | 來源審查進行中 |
CHN | 可用 | 尚不可用 | 國家假日休息日；不包括補班工作日 |
FRA | 可用 | 可用 | 常見的全國法定假日；不包括地區性增加的假日 |
DEU | 尚不可用 | 尚不可用 | 來源審查進行中 |
IND | 尚不可用 | 尚不可用 | 來源審查進行中 |
IDN | 可用 | 尚不可用 | 全國假日和集體休假分別標注 |
ITA | 尚不可用 | 尚不可用 | 來源審查進行中 |
JPN | 可用 | 可用 | 全國公共假日 |
MEX | 尚不可用 | 尚不可用 | 來源審查進行中 |
KOR | 尚不可用 | 尚不可用 | 來源審查進行中 |
RUS | 尚不可用 | 尚不可用 | 來源審查進行中 |
SAU | 尚不可用 | 尚不可用 | 來源審查進行中 |
ZAF | 尚不可用 | 可用 | 全國公共假日；不包括僅限學校的假日 |
TUR | 尚不可用 | 尚不可用 | 來源審查進行中 |
GBR | 可用 | 可用 | 英格蘭和威爾士、蘇格蘭及北愛爾蘭的銀行假日 |
USA | 可用 | 可用 | 聯邦僱員假日及補休日；不包括州假日 |
目標仍為十九個國家。澳大利亞目前僅覆蓋新南威爾士；法國不含額外地區性節假日；美國日曆覆蓋聯邦僱員；英國銀行假日保留已發布的三個地區劃分；中國不含補班日，印度尼西亞將國定假日與集體休假分開。
已發布年份包含 1–400 個事件。缺失或撤回的覆蓋範圍會返回 503 calendar_coverage_unavailable。按日期查詢成功時，僅在該年份已發布的情況下才可能返回空陣列。公共假日不代表銀行或交易所必然休市。
成功呼叫（包括空日期結果）每次消耗一個共享月度請求。錯誤不消耗月度額度；短窗口限流仍適用。 閱讀共享錯誤與配額合約.