日付に営業日数を加算する

APIで営業日数を加算する

GET /v1/calendars/holidays/{country}/{year}で、計算に必要な国と年の祝日の日付を取得します。Python関数はその日付を集合に保存し、1日ずつ進みながら各日付と照合します。平日で、祝日の集合に含まれない日付だけを数えます。除外した日付では残りの営業日数は変わりません。

1. APIキーを設定 無料のAPIキーを取得し、環境変数NARWHAL_API_KEYに保存します。スクリプトはその変数を読み取り、Authorization: Bearer YOUR_KEYとしてキーをhttps://api.narwhalapi.comに送信します。
2. 開始日と国を選択 add_business_daysに開始日、加算する営業日数、国コードを渡し、国コードを省略した場合はUSAが使われます。開始日を0日目とし、関数は日付を進めてから集計対象かどうかを判定します。
3. 計算を実行 米国で2026年11月20日（金曜日）に5営業日を加算するには、スクリプト末尾の呼び出しを使用します。週末と2026年11月26日（木曜日）の感謝祭を除外し、2026-11-30を出力します。
   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 add_business_days(start: date, n: int, country: str = "USA") -> date:
       off, loaded, day = set(), set(), start
       while n > 0:
           day += timedelta(1)
           if day.year not in loaded:
               off |= holidays(country, day.year)
               loaded.add(day.year)
           if day.weekday() < 5 and day.isoformat() not in off:
               n -= 1
       return day
   
   print(add_business_days(date(2026, 11, 20), 5))

1回の計算で各年を読み込むのは1回だけです。日付が1月1日に進むと、その年の日付を数える前に、その年の祝日カレンダーをリクエストします。loaded集合は取得済みの年を記録し、offはそれらの年の祝日の日付を保持します。指定した営業日数を数え終わるまで日付を進め、到達した日付を返します。

holidays関数はレスポンスのholidays配列を読み取り、各項目からdateを取得します。日付を進めながらそれらの値をday.isoformat()と比較し、day.weekday()で平日の条件を確認します。両方の条件を満たした場合にだけnを減らします。週末に当たる祝日も除外され、ループは毎回暦日で1日進むため、その日付で残りの営業日数が減ることはありません。戻り値は、数え終わった時点で到達した日付です。

ExcelまたはGoogle Sheetsを使用

ExcelまたはGoogle Sheetsで、Holidaysという名前の範囲に2026年11月26日を入力し、開始日と営業日数を指定してWORKDAYを使用します。2026年11月20日（金曜日）に5営業日を加算すると、数式は2026年11月30日を返します。祝日の範囲は週末とともに除外する日付を指定するため、計算に該当する祝日を含めてください。

=WORKDAY(DATE(2026,11,20), 5, Holidays)

結果のセルの表示形式を日付に設定します。WORKDAYはシリアル値を返すため、セルを日付形式にすると結果が暦日として表示されます。別の曜日を週末とする計算にはWORKDAY.INTLを使用します。数式は指定した祝日を使用するため、開始日、営業日数、祝日の範囲を目的の計算に合わせてください。数式の例では、DATE(2026,11,20)が開始日、5が営業日数を指定します。Holidaysは2026年11月26日を含む範囲を参照します。別の開始日で使う場合は、開始日の入力を変更し、該当する祝日を指定します。

状況に応じた方法の選び方

開始日が祝日や週末の場合はどうなりますか？

開始日の後の最初の営業日が1日目です。2026年11月28日（土曜日）の1営業日後は2026年11月30日（月曜日）で、日曜日を飛ばし、月曜日を加算対象の営業日として数えます。開始日自体が祝日の場合も同じ規則を適用します。その翌日から数え始め、週末と祝日を除外して進みます。

営業日数を減算できますか？

はい。timedelta(-1)で日付をさかのぼりながら週末と祝日を除外するか、スプレッドシートで=WORKDAY(start, -5, Holidays)を使用します。この数式は指定した祝日の範囲を使い、開始日から5営業日を差し引きます。掲載のPythonスクリプトは日付を先に進めるため、関数を変更する際はさかのぼる規則を適用してください。

その年の祝日カレンダーが未公開の場合はどうなりますか？

APIはその国と年に対して404 calendar_not_publishedを返します。スクリプトのraise_for_status()がこのレスポンスでエラーを発生させるため、掲載の関数はそこで停止します。週末だけを除外して結果に印を付けるよう変更するか、後で再試行できます。週末だけを除外する場合は、祝日の扱いが分かるように返された日付に印を付けてください。

計算例：2026年11月20日（金曜日）の5営業日後

2026年11月20日（金曜日）を0日目とします。週末を飛ばし、11月23日（月曜日）、24日（火曜日）、25日（水曜日）をそれぞれ1、2、3営業日目として数えます。11月26日（木曜日）は米国の感謝祭なので、営業日数は3のままです。11月27日（金曜日）が4営業日目です。

2026年11月28日（土曜日）と29日（日曜日）を除外します。11月30日（月曜日）が5営業日目となり、結果は2026-11-30です。感謝祭の祝日がなければ、11月26日（木曜日）が4営業日目、27日（金曜日）が5営業日目となり、結果は2026年11月27日（金曜日）になります。