計算兩個日期之間的營業日

使用 API

Narwhal 沒有營業日端點。使用 GET /v1/calendars/holidays/{country}/{year} 讀取指定國家及年份的國定假日，再計算未列在清單中的平日。此處的營業日是指星期一至星期五，且在所選國家不是國定假日的日期。每個國家及年份各需要一次請求，跨年度的日期範圍也需要為每個年份分別發出請求。

1. 取得你的 API 金鑰 取得免費 API 金鑰，並將它存放在 NARWHAL_API_KEY 環境變數中。指令碼會透過 Authorization: Bearer YOUR_KEY 標頭，將金鑰傳送至 https://api.narwhalapi.com。
2. 選擇國家與日期範圍 使用 ISO 3166 alpha-3 國家代碼，例如 USA、GBR、JPN、DEU 或 IDN。範例使用 USA，計算範圍為 2026 年 12 月 1 日至 31 日，包含起訖日期。
3. 計算不在假日集合中的平日 將所選日期代入這段 Python 指令碼。它會將範圍內每個年份的假日日期收集到集合中，再計算未列在集合中的星期一至星期五日期。
   Python，兩個日期之間的營業日

   import os
   from datetime import date, timedelta
   import requests
   
   API = "https://api.narwhalapi.com"
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   def holidays(country: str, year: int) -> set[str]:
       r = requests.get(
           f"{API}/v1/calendars/holidays/{country}/{year}", headers=HEADERS, timeout=10
       )
       r.raise_for_status()
       return {h["date"] for h in r.json()["holidays"]}
   
   
   def business_days(start: date, end: date, country: str = "USA") -> int:
       """Business days from start to end, counting both ends, like NETWORKDAYS."""
       off = set()
       for year in range(start.year, end.year + 1):
           off |= holidays(country, year)
       days = (start + timedelta(n) for n in range((end - start).days + 1))
       return sum(1 for d in days if d.weekday() < 5 and d.isoformat() not in off)
   
   
   print(business_days(date(2026, 12, 1), date(2026, 12, 31)))

4. 查看所選範圍的結果 以美國 2026 年 12 月 1 日至 31 日為例，指令碼會輸出 22。未來年份的行事曆發布後即可查詢；尚未發布的行事曆會回傳 404 calendar_not_published。

美國聯邦政府 2026 年行事曆有 11 個假日日期：1 月 1 日、1 月 19 日、2 月 16 日、5 月 25 日、6 月 19 日、7 月 3 日、9 月 7 日、10 月 12 日、11 月 11 日、11 月 26 日及 12 月 25 日。若範圍僅限 2026 年 12 月，這份全年清單中落在範圍內的日期就是聖誕節。

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

在 Excel 或 Google Sheets 中，將假日日期放在同一欄，並以該欄作為 Holidays 範圍。從 Narwhal 假日行事曆 (英文)的國家頁面複製日期，或從 API 回應取得日期。公式會計算起訖日期之間的平日，並排除假日欄中的日期。範圍包含起訖日期。

=NETWORKDAYS(DATE(2026,12,1), DATE(2026,12,31), Holidays)

以美國 2026 年 12 月為例，若 Holidays 範圍只有一個儲存格，內容為 2026-12-25，結果就是 22。若未提供假日範圍，公式的結果會是 23，因為它只計算平日，沒有扣除聖誕節。假日欄必須對應到計算的國家及年份。跨年度的範圍需要每個年份的假日日期。

若不使用指令碼或試算表公式，可從該國的行事曆頁面查找國定假日日期。計算所選範圍內星期一至星期五的日期，再扣除清單中落在這些平日的假日。

各種情況適合的方式

計算是否包含起訖日期？

是。Python 指令碼和 NETWORKDAYS 都包含起訖日期。起訖日期本身仍須符合營業日條件：星期六、星期日或國定假日都不會計入總數。包含起訖日期是指計算範圍；實際計入哪些日期，則由平日與假日規則決定。

若要計算過夜天數或排除結束日期，當結束日期是營業日時，將結果減去 1。若結束日期已因週末或國定假日而被排除，營業日總數就維持不變。

假日落在週末時，計算有何不同？

若該國有補假，請使用補假日期。API 會以 observed: true 標示補假日。美國 2026 年行事曆將獨立紀念日列在 7 月 3 日星期五，因為 7 月 4 日是星期六。

計算 2026 年 7 月 1 日至 31 日時，請從平日總數中扣除 7 月 3 日星期五。7 月 4 日星期六本來就不在星期一至星期五的計算範圍內，因此不需要再扣除。補假日請使用行事曆提供的日期。

週末或地區假日不同時怎麼辦？

使用符合所需行事曆的週末設定與假日範圍。Python 指令碼假設星期六和星期日為週末。若要在試算表中將星期五及星期六設為週末，請使用 NETWORKDAYS.INTL(start, end, 7, Holidays)。

假日項目包含 date、name、scope 和 subdivision_codes，有時也包含 local_name。處理地區行事曆時，請使用適用範圍及行政區欄位，再依日期去除重複項目。2026 年的 GBR 分別列出英格蘭與威爾斯、北愛爾蘭及蘇格蘭的項目：共 28 筆，涵蓋 14 個不同日期。

銀行、交易所及公司的行事曆可能與國定假日行事曆不同。美國清單的適用範圍是 federal_government；NYSE 在 2026 年 4 月 3 日耶穌受難日休市，但該日期不在聯邦假日清單中。若所需行事曆不同，請自行提供清單。

計算範例：美國，2026 年 12 月 1 日至 31 日

2026 年 12 月有 31 天，從 12 月 1 日星期二開始。計入該月的首尾日期後，共有 23 個平日。聖誕節落在 2026 年 12 月 25 日星期五，因此要扣除這個落在平日的假日。

第二個範圍包含 2026 年 11 月 20 日及 12 月 4 日。其中的平日為 11 月 20、23、24、25、26、27、30 日，以及 12 月 1、2、3、4 日。合計為 11 個平日。感恩節落在 2026 年 11 月 26 日星期四；扣除後共有 10 個營業日。