檢查指定日期是否為國定假日

使用 API

若已有要檢查的國家及日期，請使用日期端點。回應包含 country、coverage 和 holidays。請讀取 holidays 中的項目，確認適用的假日、適用範圍及相關行政區，避免將每個回傳項目都視為不同的假日日期。

1. 取得你的 API 金鑰 建立免費金鑰，並將它存放在環境變數 NARWHAL_API_KEY 中。以 Authorization: Bearer YOUR_KEY 傳送金鑰；curl 指令會在授權標頭中使用該環境變數。
2. 查詢該國的指定日期 將所需國家及日期代入 GET /v1/calendars/holidays/{country}/on/{date}。這個請求會查詢英國在 2026 年 12 月 28 日的假日。
   curl，單一日期的假日

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/GBR/on/2026-12-28"

3. 讀取假日清單 holidays 清單為空表示查詢日期在當地不是假日。清單有內容時會列出該日期的假日項目，請根據各項目的範圍和行政區，判斷是否符合你需要的假日行事曆。
4. 尋找指定日期當天或之後的假日 需要尋找起始日期當天或之後的假日時，請使用下一個假日端點。以美國為例，from_date=2026-10-24 會在 holiday 中回傳 2026 年 11 月 11 日的退伍軍人節。
   curl，指定日期當天或之後的假日

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/USA/next?from_date=2026-10-24"

如果請求回傳錯誤，請讀取 application/problem+json 回應。其中的 status、code 和 detail 說明錯誤，request_id 則用來識別請求。請使用成功回應中的假日清單來判斷日期；錯誤回應不會提供假日查詢結果。

使用試算表或不寫程式的方式

如果想直接查詢日期而不發出 API 請求，請到 Narwhal 假日行事曆 (英文)查找國家。先選擇你需要的國家行事曆：聖誕節當週的範例分別使用美國和英國的結果，同一國家內的地區項目也可能影響判斷。

在 Excel 或 Sheets 中，將一欄假日日期命名為 Holidays，並把要檢查的日期放在 A2。公式會檢查該日期是否出現在假日欄中。請使用要查詢國家的假日清單，因為公式只會檢查日期是否在你提供的清單內。

=COUNTIF(Holidays, A2)>0

使用美國假日清單時，公式對 2026 年 12 月 25 日回傳 TRUE，對 2026 年 12 月 24 日回傳 FALSE。這些結果取決於 Holidays 中的假日日期；公式本身不會向 API 請求國家行事曆。

清單檢查只需判斷日期是否出現在你選擇的清單中。即使不同地區的項目使用同一日期，公式仍能做出判斷。若要確認項目適用於哪個地區，請先讀取 API 回應中的行政區資訊，再將日期加入清單。

各種情況適合的方式

若要使用全年清單，請參閱在程式碼中加入假日檢查。指定日期的假日端點用來查詢提供的日期，下一個假日端點則接受起始日期並回傳假日日期。如果要判斷某個日期是否為假日，請在請求中保留該日期。如果要尋找該日期當天或之後的假日，請將它設為 from_date。

為什麼回應會多次列出同一個假日？

假日因地區而異時，API 會為每組行政區回傳一個項目。以英國 2026 年 12 月 28 日的節禮日補假為例，會回傳三個項目：英格蘭與威爾斯合為一組、北愛爾蘭，以及蘇格蘭。

合併項目的行政區代碼為 GB-ENG 和 GB-WLS，北愛爾蘭為 GB-NIR，蘇格蘭為 GB-SCT。每個項目的範圍都是 bank，並設有 observed: true。這些是同一假日日期的地區項目，請同時查看名稱和行政區分組。

observed: true 是什麼意思？

這表示假日適逢週末，該日期是補假日。2026 年 12 月 26 日的節禮日是星期六，因此銀行假日為 2026 年 12 月 28 日星期一。

在這個範例中，檢查日期是否在銀行假日行事曆內時，請使用銀行假日的補假日期。observed 欄位說明回傳日期為何與假日原定日期不同；這兩個日期都屬於同一個節禮日範例。

如何排除集體休假日？

傳入 scope=national_public，即可從結果中排除印尼的集體休假日。印尼的集體休假日有獨立的 collective_leave 範圍，因此未加上此篩選條件的請求可能包含這些日期。

選填的 scope 篩選條件會將結果限制在單一範圍內。可用值包括 national_public、bank、federal_government 和 collective_leave。請先選擇符合所需行事曆的範圍，再解讀回傳的假日項目。

實作範例：美國與英國的 2026 年聖誕節當週

先查詢美國的 2026 年 12 月 24 日。回傳的空白清單表示該日不是假日。接著查詢同一國家的 2026 年 12 月 25 日：聖誕節會以 federal_government 範圍出現，表示該日是這份行事曆中的假日。

以英國為例，查詢 2026 年 12 月 25 日，並讀取範圍為 bank 的聖誕節項目。接著查詢 2026 年 12 月 28 日，取得節禮日補假項目。記錄每筆結果時，請一併保留國家、日期和範圍。