두 날짜 사이의 영업일 계산

API 사용 방법

Narwhal에는 영업일 엔드포인트가 없습니다. GET /v1/calendars/holidays/{country}/{year}로 해당 국가와 연도의 공휴일을 조회한 다음, 목록에 없는 평일 수를 세세요. 여기서 영업일은 선택한 국가의 공휴일이 아닌 월요일부터 금요일까지를 뜻합니다. 국가와 연도별로 요청이 하나씩 필요하며, 기간이 여러 해에 걸치면 각 연도를 별도로 요청해야 합니다.

1. API 키 받기 무료 API 키를 받아 NARWHAL_API_KEY 환경 변수에 저장하세요. 스크립트는 Authorization: Bearer YOUR_KEY 헤더에 키를 담아 https://api.narwhalapi.com으로 보냅니다.
2. 국가와 날짜 범위 선택 USA, GBR, JPN, DEU, IDN 같은 ISO 3166 alpha-3 국가 코드를 사용하세요. 예시에서는 USA를 사용하며, 2026년 12월 1일부터 31일까지 시작일과 종료일을 모두 포함해 계산합니다.
3. 공휴일 집합에 없는 평일 계산 선택한 날짜로 이 Python 스크립트를 실행하세요. 해당 기간에 포함된 모든 연도의 공휴일 날짜를 집합에 모은 다음, 집합에 없는 월요일부터 금요일까지의 날짜만 셉니다.
   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 business_days(start: date, end: date, country: str = "USA") -> int:
       """Business days from start to end, counting both ends, like NETWORKDAYS."""
       off = set()
       for year in range(start.year, end.year + 1):
           off |= holidays(country, year)
       days = (start + timedelta(n) for n in range((end - start).days + 1))
       return sum(1 for d in days if d.weekday() < 5 and d.isoformat() not in off)
   
   
   print(business_days(date(2026, 12, 1), date(2026, 12, 31)))

4. 선택한 기간의 결과 확인 미국의 2026년 12월 1일부터 31일까지를 계산하면 스크립트는 22를 출력합니다. 미래 연도도 캘린더가 게시되어 있으면 사용할 수 있으며, 게시되지 않은 캘린더는 404 calendar_not_published를 반환합니다.

2026년 미국 연방 정부 캘린더에는 1월 1일, 1월 19일, 2월 16일, 5월 25일, 6월 19일, 7월 3일, 9월 7일, 10월 12일, 11월 11일, 11월 26일, 12월 25일의 11개 공휴일 날짜가 있습니다. 2026년 12월만 계산한다면 이 연간 목록에서 해당 기간에 포함되는 날짜는 크리스마스입니다.

스프레드시트 또는 코드 없이 계산

Excel이나 Google Sheets에서 공휴일 날짜를 열에 입력하고 해당 열을 Holidays 범위로 사용하세요. Narwhal 공휴일 캘린더 (영어)의 국가별 페이지에서 날짜를 복사하거나 API 응답에서 가져오세요. 수식은 두 날짜 사이의 평일 수를 세고 공휴일 열의 날짜를 제외합니다. 시작일과 종료일을 모두 포함합니다.

=NETWORKDAYS(DATE(2026,12,1), DATE(2026,12,31), Holidays)

미국의 2026년 12월을 계산할 때 2026-12-25가 들어 있는 단일 셀을 Holidays 범위로 지정하면 결과는 22입니다. 공휴일 범위를 지정하지 않으면 크리스마스를 빼지 않고 평일 수를 세므로 결과는 23입니다. 공휴일 열은 계산하려는 국가와 연도에 맞게 유지하세요. 기간이 여러 해에 걸치면 각 연도의 공휴일 날짜가 필요합니다.

스크립트나 스프레드시트 수식 없이 계산하려면 해당 국가의 캘린더 페이지에서 공휴일 날짜를 확인하세요. 선택한 기간에서 월요일부터 금요일까지의 날짜 수를 센 다음, 목록의 공휴일 중 해당 평일에 속하는 날짜 수를 빼세요.

상황별 계산 방법

시작일과 종료일도 포함하나요?

네. Python 스크립트와 NETWORKDAYS는 시작일과 종료일을 모두 포함합니다. 다만 두 날짜도 영업일 조건을 충족해야 하므로, 토요일이나 일요일 또는 공휴일이면 합계에 포함되지 않습니다. 양 끝을 포함한다는 것은 날짜 범위를 뜻하며, 실제로 계산에 포함되는 날짜는 평일과 공휴일 규칙에 따라 결정됩니다.

숙박 일수를 계산하거나 종료일을 제외하려면 종료일이 영업일일 때 1을 빼세요. 종료일이 주말이나 공휴일로 이미 제외되어 있다면 영업일 합계를 그대로 두세요.

공휴일이 주말이면 무엇이 달라지나요?

해당 국가에서 대체 휴일을 지정하면 그 날짜를 사용하세요. API는 대체 휴일을 observed: true로 표시합니다. 2026년 미국 캘린더에서는 7월 4일이 토요일이므로 독립기념일이 7월 3일 금요일로 기재되어 있습니다.

2026년 7월 1일부터 31일까지를 계산할 때는 평일 수에서 7월 3일 금요일을 제외하세요. 7월 4일 토요일은 이미 월요일부터 금요일까지의 계산에서 제외되므로 추가로 뺄 필요가 없습니다. 대체 휴일은 캘린더에 제공된 날짜를 사용하세요.

주말이나 지역별 공휴일이 다르면 어떻게 하나요?

사용하는 캘린더에 맞는 주말과 공휴일 범위를 적용하세요. Python 스크립트는 토요일과 일요일을 주말로 간주합니다. 스프레드시트에서 금요일과 토요일을 주말로 지정하려면 NETWORKDAYS.INTL(start, end, 7, Holidays)를 사용하세요.

공휴일 항목에는 date, name, scope, subdivision_codes가 있으며, local_name이 포함되기도 합니다. 지역별 캘린더에는 범위와 하위 지역 필드를 사용한 다음, 날짜를 기준으로 중복을 제거하세요. 2026년 GBR에는 잉글랜드·웨일스, 북아일랜드, 스코틀랜드의 항목이 별도로 있으며, 28개 행에 서로 다른 날짜 14개가 포함됩니다.

은행, 거래소, 회사의 캘린더는 공휴일 캘린더와 다를 수 있습니다. 미국 목록의 범위는 federal_government이며, NYSE가 휴장하는 2026년 4월 3일 성금요일은 해당 연방 목록에 없습니다. 필요한 캘린더가 다르면 직접 준비한 목록을 사용하세요.

계산 예시: 미국, 2026년 12월 1일부터 31일까지

2026년 12월은 31일까지 있으며 12월 1일 화요일에 시작합니다. 월의 첫날과 마지막 날을 모두 포함하면 평일은 23일입니다. 크리스마스는 2026년 12월 25일 금요일이므로 이 평일 공휴일을 빼세요.

두 번째 기간은 2026년 11월 20일과 12월 4일을 모두 포함합니다. 평일은 11월 20일, 23일, 24일, 25일, 26일, 27일, 30일과 12월 1일, 2일, 3일, 4일입니다. 평일은 총 11일입니다. 추수감사절은 2026년 11월 26일 목요일이므로 이를 빼면 영업일은 10일입니다.