國定假日 API 參考

公開測試版已上線

使用你的 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 。國家和日期／年份參數為必填。可透過選填的 scope 篩選條件選擇假日類別。不提供分頁或行政區篩選功能。

共用假日物件

欄位	類型	含義
`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	明確標示是否為補假或替代假日。Null 表示未知，而非 false。

一般假日物件包含全部七個欄位。每個回應也包含資料涵蓋範圍聲明，提供 scope、nationwide 和 subdivision_codes，即使指定日期的查詢結果為空也會包含。請求 ID 和配額仍保留在標頭中。成功回應的主體不包含來源 URL 和資料匯入檢查時間。

涵蓋範圍與限制

已發布的官方數據和文件說明來源、範圍、期間與限制。
國家	2026	2027	已發布的涵蓋範圍
`ARG`	可用	尚不可用	全國國定假日
`AUS`	可用	可用	僅限新南威爾斯州：地區國定假日與銀行假日
`AUT`	可用	可用	全國國定假日
`BEL`	可用	可用	全國國定假日
`BRA`	可用	尚不可用	聯邦政府國定假日；不含選擇性休假及部分休業
`CAN`	可用	可用	適用於受聯邦規範的民營雇主之全國法定假日基本標準；不含省級行事曆及聯邦公務人員行事曆
`CHN`	可用	尚不可用	全國假期；不包含補班日
`COL`	可用	可用	全國國定假日
`CZE`	可用	可用	全國國定假日；不含重要紀念日、一般星期日與雇主自行安排的休業
`DEU`	可用	尚不可用	全國共同國定假日；不含各州額外假日
`DNK`	可用	可用	Danmarks Nationalbank 休業日；並非一般勞工休假行事曆
`ESP`	可用	尚不可用	全國國定假日
`EST`	可用	可用	全國國定假日及休息日；不含全國性重要紀念日與縮短工時的工作日
`FRA`	可用	可用	全國共同適用的法定假日；不含地區額外假日
`GBR`	可用	可用	英格蘭與威爾斯、蘇格蘭及北愛爾蘭的銀行假日
`HKG`	可用	可用	香港公眾假期；不含一般星期日
`HRV`	可用	可用	全國國定假日與非工作日；不含紀念日與宗教節日
`IDN`	可用	可用	全國假日與集體休假，分別標示
`IND`	尚不可用	尚不可用	來源審查進行中
`IRL`	可用	可用	全國國定假日；不含個別雇主的替代休假安排與休假權益
`ITA`	可用	可用	全國民用國定假日；不含地區及雇主自行安排的休業
`JPN`	可用	可用	全國國定假日
`KOR`	尚不可用	尚不可用	來源審查進行中
`LTU`	可用	可用	依「勞動法」第 123 條規定的全國國定假日；不含地區活動
`LUX`	可用	可用	全國國定假日
`LVA`	可用	可用	全國國定假日；不含紀念日與地區活動
`MEX`	可用	可用	全國法定勞工休息日；不含銀行休業日、僅適用於州或市鎮的休息日，以及特定產業的休業日
`NLD`	可用	可用	全國國定假日；是否休假取決於僱傭條款
`NOR`	可用	尚不可用	Norges Bank 結算系統休業日；並非一般勞工休假行事曆
`NZL`	可用	可用	全國國定假日及補假日期；不含地區紀念日
`PHL`	尚不可用	尚不可用	來源審查進行中
`POL`	可用	可用	全國國定假日；不含一般星期日、地區活動與雇主自行安排的休業
`PRT`	可用	可用	全國強制放假的國定假日；不含選擇性、市鎮及地區假日
`RUS`	尚不可用	尚不可用	來源審查進行中
`SAU`	尚不可用	尚不可用	來源審查進行中
`SGP`	可用	可用	全國國定假日與來源指定的補假日期
`SVK`	可用	可用	全國國定假日
`SVN`	可用	可用	全國國定假日與休息日；不含不放假的紀念日與地方假日
`SWE`	可用	可用	全國國定假日
`TUR`	尚不可用	尚不可用	來源審查進行中
`TWN`	可用	可用	政府機關辦公行事曆；不含民營部門休業日與市場休市日
`USA`	可用	可用	聯邦員工假日及補假日期；不含州假日
`ZAF`	可用	可用	全國國定假日；不包括僅限學校的假日

可用項目僅描述列明範圍，不涵蓋所有地方或行業假日。年份輸入允許1900–2200，但不代表提供歷史涵蓋範圍。

已發布的年份包含 1–400 個事件。若該年份的資料未提供或已撤回，會回傳 503 calendar_coverage_unavailable。指定日期查詢成功時，只有在該年份的日曆已發布的情況下才可能回傳空陣列。國定假日不代表銀行必定休業或交易所必定休市。

每次成功呼叫都會消耗一次共用的每月請求配額，包括指定日期查詢結果為空的情況。錯誤不會消耗每月配額；短時間視窗的速率限制仍適用。閱讀共用錯誤與配額規範。