국가별 공휴일 일정을 피해 회의와 릴리스 일정 잡기

한 나라가 다음에 언제 쉬는지 조회하기

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. API 키 받기 가입에서 API 키를 받아 NARWHAL_API_KEY에 보관하세요.
2. 국가와 기간 나열하기 스크립트는 USA, DEU, JPN, IDN을 사용해 11월 9일부터 30일 사이에서 연속된 3영업일의 빈 구간을 찾습니다. 3일은 예시이므로 릴리스나 점검 시간대에 필요한 길이로 바꾸세요. 국가 목록과 날짜도 팀에 맞게 바꾸세요.
3. 휴무 날짜 모으기 국가당 한 번의 요청으로 그해의 공휴일이 반환됩니다. 스크립트는 각 date를 날짜에서 쉬는 국가 집합으로 가는 맵에 저장합니다. 두 나라가 공유하는 날짜에는 두 코드가 모두 들어갑니다.
4. 평일을 훑으며 보고하기 스크립트는 적어도 한 나라가 쉬는 평일을 나열한 뒤, 처음으로 이어지는 빈 영업일 구간을 찾습니다.
   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일은 네 나라 모두 비어 있습니다. 연속된 3영업일의 첫 빈 구간은 11월 12일 목요일부터 시작합니다. 스크립트는 scope 필터를 쓰지 않으므로 인도네시아의 집단 휴가일도 휴무로 셉니다. 이를 빼려면 그 나라의 요청에 scope=national_public을 추가하세요.

일정에서 빼야 할 휴무일

11월 11일 수요일에 릴리스를 잡으면 쉬는 미국 사무실과 겹칩니다. 두 추수감사절은 서로 다른 나라의 다른 공휴일로, holiday_key 값은 각각 labor_thanksgiving_day와 thanksgiving_day이며 각자 자기 나라만 쉽니다. 이름이 아니라 키로 매칭하면 둘을 구분할 수 있습니다.

휴무일을 일정을 잡는 사람들의 눈앞에 두려면 POST /v1/calendars/subscriptions로 include_holidays는 true, include_releases는 false로 캘린더 피드를 만드세요. 요청은 캘린더 구독 문서에 설명되어 있습니다. 이 호출은 피드를 생성하므로 이 페이지에서는 실행하지 않았습니다.

이 비교에서 각 scope가 다루는 범위

목록을 믿기 전에 각 응답의 coverage를 읽으세요. 달력이 다루는 scope와 하위 지역이 적혀 있으며, scope는 나라마다 다릅니다. 항목에 하위 지역 코드가 붙는 나라, 예를 들어 영국은 확인이 하나 더 필요합니다. 목록이 비어 있거나 사무실이 있는 지역을 포함할 때 그 항목을 남기세요.

주말 공휴일도 일정에 영향을 주나요?

평일을 훑는 처리에서는 상관없습니다. 스크립트는 월요일부터 금요일까지만 보므로 토요일이나 일요일의 공휴일은 건너뜁니다. 일부 국가는 그날을 평일로 옮기고 새 항목에 observed를 붙이는데, 그 항목은 평일 날짜이므로 휴무로 나타납니다.

팀이 지역별 공휴일이 있는 나라에서 일한다면?

연도 엔드포인트에는 지역 파라미터가 없으므로 코드에서 subdivision_codes로 필터링하세요. 목록이 비어 있으면 그 공휴일은 전국 공통입니다. 영국에서는 각 은행 휴일이 국가 그룹마다 한 번씩 나타나므로, 한 날짜에 항목이 여러 개 있을 수 있습니다.

여러 해에 걸친 기간에는 요청이 몇 번 필요한가요?

국가와 연도마다 한 번입니다. 12월 31일을 넘기는 기간에는 각 나라의 다음 해 목록도 필요하며, 달력이 발표되지 않은 해에는 코드 calendar_not_published가 담긴 404가 반환됩니다. 장기 일정에서는 이 응답에 대비하고, 반복 실행 때 다시 요청하지 않도록 연도별 목록을 캐시해 두세요.