날짜에 영업일 더하기

API로 영업일 더하기

GET /v1/calendars/holidays/{country}/{year}로 계산에 필요한 국가와 연도의 공휴일 날짜를 가져오세요. Python 함수는 이 날짜들을 집합에 저장하고 이동 중인 각 날짜와 비교합니다. 평일이면서 공휴일 집합에 없는 날짜만 계산에 포함됩니다. 건너뛴 날짜는 남은 영업일 수를 줄이지 않습니다.

1. API 키 설정 무료 API 키를 받아 환경 변수 NARWHAL_API_KEY에 저장하세요. 스크립트는 이 변수를 읽고 키를 Authorization: Bearer YOUR_KEY로 지정해 https://api.narwhalapi.com으로 보냅니다.
2. 시작일과 국가 선택 add_business_days에 시작일, 더할 영업일 수, 국가 코드를 전달하세요. 함수의 기본 국가 코드는 USA입니다. 시작일은 0일째이므로, 함수는 다음 날짜로 이동한 뒤 해당 날짜를 합계에 포함할지 판단합니다.
3. 계산 실행 미국에서 2026년 11월 20일 금요일에 5영업일을 더하려면 스크립트 끝의 호출을 사용하세요. 주말과 2026년 11월 26일 목요일 추수감사절을 건너뛴 결과인 2026-11-30을 출력합니다.
   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 add_business_days(start: date, n: int, country: str = "USA") -> date:
       off, loaded, day = set(), set(), start
       while n > 0:
           day += timedelta(1)
           if day.year not in loaded:
               off |= holidays(country, day.year)
               loaded.add(day.year)
           if day.weekday() < 5 and day.isoformat() not in off:
               n -= 1
       return day
   
   
   print(add_business_days(date(2026, 11, 20), 5))

계산 중 각 연도는 한 번만 불러옵니다. 날짜 이동 중 1월 1일을 지나면, 함수는 해당 연도의 날짜를 계산에 포함하기 전에 그해의 공휴일 캘린더를 요청합니다. loaded 집합은 이미 불러온 연도를 기록하고, off는 해당 연도들의 공휴일 날짜를 저장합니다. 요청한 영업일 수를 모두 채울 때까지 이동한 다음, 도달한 날짜를 반환합니다.

holidays 함수는 응답의 holidays 배열을 읽고 각 항목에서 date를 가져옵니다. 날짜를 이동하면서 이 값들을 day.isoformat()과 비교하고, day.weekday()로 평일 조건을 확인합니다. 두 조건을 모두 충족해야 n이 줄어듭니다. 주말에 해당하는 공휴일도 건너뛰는 날짜로 처리되며, 반복문은 매번 달력상 하루씩 이동하고 해당 날짜는 남은 수를 줄이지 않습니다. 반환값은 계산을 마쳤을 때 도달한 날짜입니다.

Excel 또는 Google Sheets 사용

Excel이나 Google Sheets에서 Holidays라는 범위에 2026년 11월 26일을 입력하고, 시작일과 영업일 수를 지정해 WORKDAY를 사용하세요. 2026년 11월 20일 금요일에 5영업일을 더하면 수식은 2026년 11월 30일을 반환합니다. 공휴일 범위는 주말 외에 건너뛸 날짜를 지정하므로, 계산에 적용되는 공휴일 날짜를 포함하세요.

=WORKDAY(DATE(2026,11,20), 5, Holidays)

결과 셀의 표시 형식을 날짜로 설정하세요. WORKDAY는 일련번호를 반환하므로, 셀의 날짜 표시 형식이 결과를 달력 날짜로 표시합니다. 다른 요일을 주말로 계산해야 하면 WORKDAY.INTL을 사용하세요. 수식은 지정한 공휴일 날짜를 사용하므로, 시작일과 영업일 수, 공휴일 범위를 원하는 계산에 맞게 설정하세요. 예시 수식에서 DATE(2026,11,20)은 시작일을, 5는 영업일 수를 지정합니다. Holidays는 2026년 11월 26일이 들어 있는 범위를 가리킵니다. 다른 시작일로 계산하려면 시작일 입력값을 바꾸고 해당 공휴일을 지정하세요.

상황별 계산 방법

시작일이 공휴일이나 주말이면 어떻게 하나요?

1일째는 시작일 다음의 첫 영업일입니다. 2026년 11월 28일 토요일에 1영업일을 더하면 2026년 11월 30일 월요일이며, 일요일을 건너뛰고 월요일이 요청한 1영업일로 계산됩니다. 시작일 자체가 공휴일인 경우에도 같은 규칙이 적용됩니다. 시작일 다음 날부터 계산하며, 이동 중 주말과 공휴일을 건너뜁니다.

영업일을 뺄 수도 있나요?

네. timedelta(-1)로 날짜를 거슬러 이동하며 주말과 공휴일을 건너뛰거나, 스프레드시트에서 =WORKDAY(start, -5, Holidays)를 사용하세요. 이 수식은 지정한 공휴일 범위를 사용해 시작일에서 5영업일을 뺍니다. 제공된 Python 스크립트는 앞으로 이동하므로, 함수를 수정할 때 뒤로 이동하는 규칙을 적용하세요.

해당 연도의 공휴일 캘린더가 게시되지 않았다면 어떻게 하나요?

API는 해당 국가와 연도에 대해 404 calendar_not_published를 반환합니다. 스크립트의 raise_for_status()가 이 응답에 오류를 발생시키므로 제공된 함수는 여기서 중단됩니다. 주말만 제외해 계산하고 결과에 표시하도록 수정하거나, 나중에 다시 시도할 수 있습니다. 주말만 제외하는 방식을 사용한다면 반환된 날짜에 이를 표시해 공휴일 처리 방식을 명확히 하세요.

계산 예시: 2026년 11월 20일 금요일의 5영업일 후

2026년 11월 20일 금요일을 0일째로 시작합니다. 주말을 건너뛰고 11월 23일 월요일, 11월 24일 화요일, 11월 25일 수요일을 각각 1, 2, 3영업일째로 셉니다. 11월 26일 목요일은 미국의 추수감사절이므로 계산값은 3으로 유지됩니다. 11월 27일 금요일이 4영업일째입니다.

2026년 11월 28일 토요일과 11월 29일 일요일을 건너뜁니다. 11월 30일 월요일이 5영업일째이므로 결과는 2026-11-30입니다. 추수감사절 공휴일이 없다면 11월 26일 목요일이 4영업일째, 11월 27일 금요일이 5영업일째가 되어 결과는 2026년 11월 27일 금요일입니다.