급여 계산을 위해 국가와 연도별 공휴일 나열하기

한 국가의 전국 공휴일 목록 가져오기

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 목록은 캘린더에 무엇이 들어 있는지 알려 줍니다. 여기서는 national_public이라는 하나의 scope이고 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를 추가하세요.

규칙이 특정 공휴일 하나를 가리킬 때는 name이 아니라 holiday_key를 키로 쓰세요. 한 국가 안에서 키는 하나의 공휴일을 가리키므로 christmas_day 규칙은 반환된 목록에서 그 공휴일만 골라내지만, 이름은 국가마다 다를 수 있는 표시용 텍스트입니다. 다른 국가에서도 같은 종류의 날에는 같은 키가 쓰이므로, 하나의 정책이 여러 국가를 다룰 때 도움이 됩니다.

한 주나 지역의 공휴일만 가져오려면 어떻게 하나요?

연도별 엔드포인트에는 하위 지역 매개변수가 없으므로 코드에서 걸러 내세요. subdivision_codes가 비어 있거나 AU-NSW 같은 코드를 포함하는 항목만 남기면 됩니다. 먼저 coverage를 읽으면 캘린더가 애초에 어떤 하위 지역을 다루는지 알 수 있습니다.

어떤 scope에 공휴일이 없는 국가는 어떻게 되나요?

API는 코드 calendar_not_published가 담긴 404 problem 응답을 반환하며, detail에 국가, 연도, 요청한 scope가 표시됩니다. 영국에 scope=regional_public으로 요청했을 때 이 응답이 반환됐는데, 영국의 항목은 bank scope를 쓰기 때문입니다. 어떤 scope가 있는지 보려면 scope 없이 요청하세요.