避開多國假日安排會議與發布

查詢某個國家下一次休息是什麼時候

GET /v1/calendars/holidays/{country}/next 回傳 from_date 當天或之後的第一個假日。這個請求查詢日本從 2026 年 11 月 9 日起的情況。

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

{
  "country": "JPN",
  "coverage": [
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holiday": {
    "date": "2026-11-23",
    "name": "Labor Thanksgiving Day",
    "holiday_key": "labor_thanksgiving_day",
    "local_name": "勤労感謝の日",
    "scope": "national_public",
    "subdivision_codes": []
  }
}

這個假日是 11 月 23 日的勤勞感謝日,scope 為 national_public。local_name 是日文名稱,holiday_key 是這類日子的穩定鍵。對單一國家來說，一次呼叫就能回答排程問題。對多個國家，可以逐一詢問並保留最早的答案，或是像下一節那樣讀取整年的資料。

一次走訪找出各國的共同空閒日

1. 取得 API 金鑰 在註冊頁取得 API 金鑰，並儲存在 NARWHAL_API_KEY 中。
2. 列出國家與時間視窗 腳本使用 USA、DEU、JPN 與 IDN,在 11 月 9 日到 30 日之間尋找連續 3 個空閒的工作日。3 天只是範例，請換成你的發布或維護時段所需的長度，也請依你自己的團隊修改國家清單與日期。
3. 蒐集休息日的日期 每個國家一次請求就回傳當年的假日。腳本把每個 date 存入一個對應表，鍵是日期，值是當天休息的國家集合。兩個國家共有的日期會同時包含兩個代碼。
4. 走訪工作日並輸出報告 腳本先列出至少有一個國家休息的工作日，再找出第一段連續的空閒工作日。
   Python,休息日與第一段連續空閒日

   import os
   from collections import defaultdict
   from datetime import date, timedelta
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   COUNTRIES = ["USA", "DEU", "JPN", "IDN"]
   START, END, NEED = date(2026, 11, 9), date(2026, 11, 30), 3
   
   closed = defaultdict(set)  # date -> countries closed that day
   for country in COUNTRIES:
       r = requests.get(
           f"https://api.narwhalapi.com/v1/calendars/holidays/{country}/{START.year}",
           headers=HEADERS,
           timeout=10,
       )
       r.raise_for_status()
       for h in r.json()["holidays"]:
           closed[h["date"]].add(country)
   
   days, day = [], START
   while day <= END:
       if day.weekday() < 5:
           days.append((day, sorted(closed.get(day.isoformat(), []))))
       day += timedelta(1)
   
   for day, who in days:
       if who:
           print(day.strftime("%a %d %b"), "closed:", ", ".join(who))
   
   for i in range(len(days) - NEED + 1):
       if all(not who for _, who in days[i:i + NEED]):
           print(f"first {NEED} clear business days in a row start:", days[i][0].strftime("%a %d %b"))
           break

Wed 11 Nov closed: USA
Mon 23 Nov closed: JPN
Thu 26 Nov closed: USA
first 3 clear business days in a row start: Thu 12 Nov

在 11 月 9 日到 30 日的 16 個工作日裡，有 3 天有休息,13 天在四個國家都是空閒的。連續 3 個空閒工作日的第一段從 11 月 12 日星期四開始。腳本沒有使用 scope 篩選，所以印尼的集體休假日會被算作休息日。要把它們排除，可以在該國的請求中加上 scope=national_public。

排程時要避開的休息日

把發布安排在 11 月 11 日週三，會撞上休息的美國辦公室。兩個感恩節是不同國家的不同假日,holiday_key 的值分別是 labor_thanksgiving_day 與 thanksgiving_day,各自只讓自己的國家休息。依鍵而不是名稱比對，就能把它們區分開。

想讓排程的人直接看到休息日，可以透過 POST /v1/calendars/subscriptions 建立日曆訂閱源，把 include_holidays 設為 true,include_releases 設為 false。請求的說明見日曆訂閱文件。因為這個呼叫會建立訂閱源，所以本頁沒有執行它。

在這次對照中各個 scope 涵蓋的範圍

依賴清單之前，先讀每個回應中的 coverage。它寫明了日曆涵蓋的 scope 與行政分區，而 scope 因國家而異。對於項目帶有分區代碼的國家，例如英國，還要多做一次檢查:當項目的清單為空，或包含辦公室所在的地區時，才保留該項目。

週末的假日對排程有影響嗎?

對走訪工作日的做法沒有影響。腳本只看週一到週五，所以落在週六或週日的假日會被跳過。有些國家會把假期順延到工作日，並在新項目上標記 observed;該項目的日期是工作日，所以會顯示為休息。

如果團隊所在的國家有地區性假日怎麼辦?

年度端點沒有地區參數，所以要在你的程式碼裡依 subdivision_codes 篩選。清單為空代表該假日全國通用。在英國，每個銀行假日對每組國家各出現一次，所以同一個日期可能有多個項目。

跨年的時間視窗需要多少次請求?

每個國家每一年一次請求。跨越 12 月 31 日的視窗，還需要每個國家下一年的清單;沒有公布日曆的年份會回傳代碼為 calendar_not_published 的 404。做長期排程時要預先處理這個回應，並把每一年的清單快取起來，這樣重複執行就不用再請求。