給与計算のために、国と年ごとの祝日を一覧にする

1つの国の全国向けリストを取得する

GET /v1/calendars/holidays/{country}/{year} は、ある国のある年の祝日を返します。任意の scope パラメータを指定すると、1種類の祝日だけが残ります。このリクエストはインドネシアの2026年を取得し、national_public だけを残します。

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026?scope=national_public"

{
  "country": "IDN",
  "coverage": [
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year’s Day",
      "holiday_key": "new_years_day",
      "local_name": "Tahun Baru 2026 Masehi",
      "scope": "national_public",
      "subdivision_codes": []
    },
    {
      "date": "2026-01-16",
      "name": "Isra and Mi’raj",
      "holiday_key": "isra_and_miraj",
      "local_name": "Isra Mikraj Nabi Muhammad S.A.W.",
      "scope": "national_public",
      "subdivision_codes": []
    }
  ]
}

coverage のリストは、カレンダーに何が含まれるかを示します。ここでは national_public という1つの scope で、subdivision_codes のリストは空です。エントリの subdivision_codes が空なら、その祝日は全国に適用されます。local_name には、分かっている場合に現地語の名称が入ります。完全なレスポンスには17日分が入っています。

別の国の地域別リストを取得する

すべての祝日が全国のものとは限りません。このリクエストは、scope を付けずにオーストラリアの2026年を取得します。

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

{
  "country": "AUS",
  "coverage": [
    {
      "scope": "bank",
      "subdivision_codes": [
        "AU-NSW"
      ]
    },
    {
      "scope": "regional_public",
      "subdivision_codes": [
        "AU-NSW"
      ]
    }
  ],
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year’s Day",
      "holiday_key": "new_years_day",
      "scope": "regional_public",
      "subdivision_codes": [
        "AU-NSW"
      ]
    },
    {
      "date": "2026-01-26",
      "name": "Australia Day",
      "holiday_key": "australia_day",
      "scope": "regional_public",
      "subdivision_codes": [
        "AU-NSW"
      ]
    }
  ]
}

ここでは、すべてのエントリの subdivision_codes が AU-NSW で、coverage には scope の bank と regional_public が並び、どちらも AU-NSW だけが対象です。このカレンダーが対象とするのはニューサウスウェールズ州です。ほかの州については何も含まれていないため、ビクトリア州に従業員がいる給与計算では別のデータ源が必要です。エントリには observed もあります。12月28日の Additional Day for Boxing Day は、土曜日にあたる12月26日の代わりの平日です。

各従業員に適用される祝日を数える

1. APIキーを取得 サインアップ で API キーを取得し、NARWHAL_API_KEY に保存します。
2. 国と従業員の地域を組み合わせる スクリプトは、IDN には地域を指定せず、AUS には AU-NSW を組み合わせます。地域は従業員の記録から取得してください。
3. 該当するエントリを残し、scope ごとにまとめる エントリは、subdivision_codes のリストが空であるか、従業員の地域を含んでいる場合に適用されます。スクリプトは日付を scope ごとにまとめ、そのうち平日にあたる日数を数えます。週末の祝日は就業日を減らさないためです。
   Python、2か国の scope ごとの祝日

   import os
   from collections import defaultdict
   from datetime import date
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   def year_list(country, year):
       r = requests.get(
           f"https://api.narwhalapi.com/v1/calendars/holidays/{country}/{year}",
           headers=HEADERS,
           timeout=10,
       )
       r.raise_for_status()
       return r.json()
   
   
   for country, region in (("IDN", None), ("AUS", "AU-NSW")):
       data = year_list(country, 2026)
       print(country, [(c["scope"], c["subdivision_codes"]) for c in data["coverage"]])
       dates = defaultdict(set)  # scope -> dates that apply to this employee
       for h in data["holidays"]:
           if not h["subdivision_codes"] or region in h["subdivision_codes"]:
               dates[h["scope"]].add(h["date"])
       for scope, days in sorted(dates.items()):
           weekdays = [d for d in days if date.fromisoformat(d).weekday() < 5]
           print("  ", scope, len(days), "dates,", len(weekdays), "on weekdays")

IDN [('collective_leave', []), ('national_public', [])]
   collective_leave 8 dates, 8 on weekdays
   national_public 17 dates, 13 on weekdays
AUS [('bank', ['AU-NSW']), ('regional_public', ['AU-NSW'])]
   bank 1 dates, 1 on weekdays
   regional_public 13 dates, 9 on weekdays

給与計算のカレンダーと比べるべき数値は、平日にあたる日数です。インドネシアは2つの scope を合わせて平日が21日、ニューサウスウェールズ州は10日です。collective_leave の日や bank の祝日が契約上の有給休暇になるかどうかは、自社の方針と現地の規則で決まります。API は各日にラベルを付けるだけで、給与の扱いは決めません。

実例：インドネシアのイード・アル＝フィトル（断食明け大祭）の週

national_public の2つの日付はどちらも週末にあたるため、scope=national_public でリクエストすると、その週に失われる就業日はないように見えます。平日の3日間、つまり3月20日（金）、23日（月）、24日（火）は、collective_leave にだけ現れます。国民の祝日だけに絞った給与計算では、これを見落とします。スクリプトがリスト全体を読み、scope ごとにまとめるのはそのためです。

scope は給与計算で何を意味しますか。

national_public は国全体の祝日です。collective_leave にはインドネシアの cuti bersama（集団休暇）が入り、カレンダーはこの追加の休日を独自の scope として載せています。regional_public と bank のエントリには、適用される場所を示す地域コードが付いています。

スクリプトのように、scope を付けずに年単位で取得し、コード側で scope ごとにまとめると、あらゆる種類の日が見えます。scope をリクエストに付けるのは、特定の給与ルールがその種類だけを必要とするときに限ってください。

ルールが特定の1つの祝日を指す場合は、name ではなく holiday_key をキーにしてください。1つの国の中でキーは1つの祝日を指すので、christmas_day のルールは返されたリストのその祝日だけを選び出します。一方、名前は表示用のテキストで、国によって異なることがあります。ほかの国でも同じ種類の日には同じキーが使われるため、1つの方針で複数の国を扱うときに役立ちます。

1つの州や地域の祝日だけを取得するにはどうしますか。

年単位のエンドポイントには地域のパラメータがないため、コード側で絞り込みます。subdivision_codes が空であるか、AU-NSW のようなコードを含むエントリを残してください。まず coverage を読むと、カレンダーがそもそもどの地域を対象としているかが分かります。

ある scope に祝日がない国ではどうなりますか。

API は、コード calendar_not_published を持つ 404 の problem レスポンスを返し、その detail に国、年、リクエストした scope が示されます。英国に scope=regional_public でリクエストしたときにこれが返りました。英国のエントリは bank の scope を使っているためです。どの scope があるかを知るには、scope を付けずにリクエストしてください。