各国 祝日 会議 日程：複数の国の祝日を避けて会議やリリースを組む

ある国が次にいつ休みになるかを調べる

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 か国なら、1 回の呼び出しで日程の判断ができます。複数の国なら、それぞれに問い合わせて最も早い答えを残すか、次のセクションのように 1 年分を読み込みます。

1 回の処理で各国の空き日を見つける

1. APIキーを取得 サインアップ で API キーを取得し、NARWHAL_API_KEY に保存します。
2. 国と期間を列挙する スクリプトは USA、DEU、JPN、IDN を使い、11月9日から30日までの間で、連続する 3 営業日の空きを探します。3 日は例なので、リリースやメンテナンス枠に必要な長さを使ってください。自分のチームに合わせて、国のリストと日付を変えます。
3. 休みの日付を集める 1 か国につき 1 回のリクエストで、その年の祝日が返ります。スクリプトは各 date を、日付から休みの国の集合へのマップに保存します。2 か国が共有する日付には、両方のコードが入ります。
4. 平日をたどって報告する スクリプトは、少なくとも 1 か国が休みの平日を一覧にし、続けて最初の連続した空き営業日を見つけます。
   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 日は 4 か国すべてで空いています。連続する 3 営業日の最初の空きは、11月12日の木曜日から始まります。スクリプトは scope による絞り込みを使っていないため、インドネシアの集団休暇日も休みとして数えます。それを除くには、その国のリクエストに scope=national_public を加えます。

日程に入れない休みの日

11月11日の水曜日にリリースを設定すると、休みの米国のオフィスに当たってしまいます。2 つの感謝祭は、別の国の別の祝日で、holiday_key の値はそれぞれ labor_thanksgiving_day と thanksgiving_day であり、休みになるのは自分の国だけです。名称ではなくキーで照合すれば、この 2 つを区別できます。

休みの日を日程を組む人の目に入れるには、POST /v1/calendars/subscriptions で include_holidays を true、include_releases を false にしてカレンダーフィードを作ります。リクエストについてはカレンダー購読のドキュメントに説明があります。この呼び出しはフィードを作成するため、このページでは実行していません。

この比較で各 scope が対象とするもの

リストに頼る前に、各レスポンスの coverage を読んでください。そこには、カレンダーが対象とする scope と地域区分が書かれており、scope は国によって異なります。エントリに地域区分コードが付く国、たとえば英国では、もう 1 つ確認が必要です。リストが空か、オフィスのある地域を含んでいるときに、そのエントリを残します。

週末の祝日は日程に関係しますか?

平日をたどる処理には関係しません。スクリプトは月曜から金曜しか見ないため、土曜や日曜の祝日はスキップされます。国によっては休みを平日に移し、新しいエントリに observed を付けます。そのエントリは平日の日付なので、休みとして現れます。

チームが地域ごとの祝日がある国で働いている場合は?

年のエンドポイントには地域のパラメータがないので、コード側で subdivision_codes を使って絞り込んでください。リストが空なら、その祝日は全国共通です。英国では、各バンクホリデーが国のグループごとに 1 回現れるため、1 つの日付に複数のエントリが付くことがあります。

複数年にまたがる期間には何回のリクエストが必要ですか?

国と年ごとに 1 回です。12月31日をまたぐ期間では、各国の翌年のリストも必要で、カレンダーが公表されていない年は、コード calendar_not_published の 404 が返ります。長期のスケジュールでは、このレスポンスに備え、同じ問い合わせを繰り返さないよう、年ごとのリストをキャッシュしておいてください。