為薪資計算列出各國各年的國定假日

取得一個國家的全國性假日清單

GET /v1/calendars/holidays/{country}/{year} 回傳某個國家某一年的假日。可選的 scope 參數只保留一種類型的假日。下面的請求查詢印尼 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 清單說明了日曆包含的內容：一個 scope，即 national_public，其 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，兩個國家各 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

平日天數就是用來和薪資日曆對照的數字。印尼兩個 scope 合計有 21 個平日日期，新南威爾斯州有 10 個。collective_leave 日或 bank 假日在您的合約中是否算帶薪休假，由您的政策和當地規定決定。API 只給每一天貼標籤，不決定薪資如何發放。

實例：印尼開齋節所在的一週

兩個 national_public 日期都落在週末，所以用 scope=national_public 請求時，那一週看起來沒有損失任何工作日。三個平日，即 3 月 20 日（週五）、23 日（週一）和 24 日（週二），只出現在 collective_leave 之下。只按全國性假日篩選的薪資計算會漏掉它們。這就是腳本讀取整個清單並按 scope 分組的原因。

各 scope 對薪資計算意味著什麼？

national_public 是全國性的假日。collective_leave 收錄印尼的 cuti bersama（集體休假），日曆把這些額外的休息日單獨列在一個 scope 下。regional_public 和 bank 項目帶有行政區劃代碼，說明它們適用的地區。

像腳本那樣，請求全年時不帶 scope，在程式碼中按它分組，這樣就能看到每一種日子。只有當某條薪資規則只需要其中一類時，才在請求中加上 scope。

當規則指向某一個特定的假日時，請以 holiday_key 而不是 name 作為鍵。在同一個國家內，鍵唯一對應一個假日，因此針對 christmas_day 的規則會在回傳的清單中選出那一個假日，而名稱只是顯示文字，可能因國家而異。其他國家的同類假日使用相同的鍵，這在一套政策涵蓋多個國家時很有幫助。

如何只取得某個州或地區的假日？

年度端點沒有行政區劃參數，所以要在程式碼中篩選：保留 subdivision_codes 為空或包含該代碼（例如 AU-NSW）的項目。請先看 coverage，因為它會顯示這份日曆究竟涵蓋哪些行政區劃。

如果一個國家在某個 scope 下沒有假日會怎樣？

API 會回傳 404 problem 回應，其代碼為 calendar_not_published，detail 中會指出國家、年份和所請求的 scope。對英國使用 scope=regional_public 發出請求時就回傳了它，因為英國的項目使用的是 bank scope。不帶 scope 請求即可看到存在哪些 scope。