코드에 공휴일 확인 추가

API 사용 방법

GET /v1/calendars/holidays/{country}/{year}는 연간 전체 데이터를 반환합니다. 수천 개의 날짜를 처리하는 작업에서도 국가와 연도 조합별로 한 번만 요청하도록 반환된 date 문자열을 국가 및 연도별로 캐시하세요. 사용하는 집합이 함수에 전달하는 날짜와 일치해야 하므로 캐시에 국가와 연도를 함께 저장하세요.

1. API 키 설정 무료 키를 발급받아 NARWHAL_API_KEY 환경 변수에 저장하세요. 스크립트는 해당 변수를 읽고 https://api.narwhalapi.com에 Authorization: Bearer YOUR_KEY로 키를 전송합니다.
2. 캐시를 사용하는 Python 함수 사용 함수는 공휴일 문자열을 frozenset에 저장하고 국가와 연도를 캐시 인수로 사용합니다. Python date로 is_business_day를 호출하면 기본 국가로 USA를 사용하며, 주말이면 공휴일을 조회하기 전에 False를 반환합니다.
   Python, 캐시를 사용하는 영업일 확인

   import os
   from datetime import date
   from functools import lru_cache
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   @lru_cache(maxsize=None)
   def holiday_dates(country: str, year: int) -> frozenset[str]:
       r = requests.get(
           f"https://api.narwhalapi.com/v1/calendars/holidays/{country}/{year}",
           headers=HEADERS,
           timeout=10,
       )
       r.raise_for_status()
       return frozenset(h["date"] for h in r.json()["holidays"])
   
   
   def is_business_day(day: date, country: str = "USA") -> bool:
       return day.weekday() < 5 and day.isoformat() not in holiday_dates(country, day.year)
   
   
   for d in (date(2026, 11, 26), date(2026, 11, 27), date(2026, 11, 28)):
       print(d, d.strftime("%a"), is_business_day(d))

3. 앱에서 JavaScript 함수 사용 JavaScript에서는 맵이 국가와 연도 조합별로 집합을 저장하고 함수는 ISO 날짜 문자열을 받습니다. 기본값인 USA 외의 캘린더가 필요하면 국가를 전달하세요. 응답 상태는 날짜가 캐시에 저장되기 전에 처리됩니다.
   JavaScript (Node 18+), 같은 영업일 확인

   const headers = { Authorization: `Bearer ${process.env.NARWHAL_API_KEY}` };
   const cache = new Map();
   
   async function holidayDates(country, year) {
     const key = `${country}-${year}`;
     if (!cache.has(key)) {
       const res = await fetch(
         `https://api.narwhalapi.com/v1/calendars/holidays/${country}/${year}`,
         { headers },
       );
       if (!res.ok) throw new Error(`Narwhal ${res.status}`);
       cache.set(key, new Set((await res.json()).holidays.map((h) => h.date)));
     }
     return cache.get(key);
   }
   
   export async function isBusinessDay(isoDate, country = "USA") {
     const day = new Date(`${isoDate}T12:00:00Z`).getUTCDay();
     if (day === 0 || day === 6) return false;
     return !(await holidayDates(country, Number(isoDate.slice(0, 4)))).has(isoDate);
   }
   
   console.log(
     await isBusinessDay("2026-11-26"),
     await isBusinessDay("2026-11-27"),
     await isBusinessDay("2026-11-28"),
   );

Free 요금제의 월 요청 한도는 5,000회이므로 날짜를 많이 처리하는 작업에서는 연간 집합을 재사용해야 합니다.

Python 캐시는 holiday_dates에 속하며, JavaScript 캐시는 함수 밖의 Map입니다. 둘 다 공휴일 날짜를 메모리에 보관해 재사용합니다. 앱에 필요하면 갱신 일정과 파일 또는 데이터베이스 저장 기능을 추가하세요. 현재 연도를 매월 갱신하고 재시작 후에도 날짜를 유지하려면 캐시 조회에 이러한 기능을 추가해야 합니다.

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

별도 탭에 공휴일 열을 두고 수식에서 범위 이름으로 Holidays를 사용하세요. 확인할 날짜를 A2에 입력하세요. 수식은 평일 여부와 공휴일 범위에서 해당 날짜가 나온 횟수를 함께 확인하므로 시트에도 스크립트와 같은 영업일 규칙이 적용됩니다. API 캐시와 마찬가지로 공휴일 열에는 확인하려는 국가와 연도의 날짜가 있어야 합니다. 다른 날짜에 수식을 사용할 때도 해당 열을 유지하세요.

=AND(WEEKDAY(A2,2)<6, COUNTIF(Holidays, A2)=0)

평일은 Holidays 범위에 일치하는 날짜가 없을 때만 TRUE를 반환합니다. 토요일이나 일요일은 해당 범위에 없어도 FALSE를 반환합니다. 열에 날짜를 저장하고 수식으로 A2의 영업일 여부를 판단하므로, 이 방식은 공휴일 날짜를 직접 편집하는 팀에 적합합니다.

상황별 계산 방법

자주 재시작하는 앱에서는 연도 및 공휴일 날짜와 함께 국가도 저장하세요. 확인할 날짜에 맞는 집합을 불러오세요. 영구 저장된 집합과 메모리의 집합은 같은 공휴일 포함 여부 규칙을 사용합니다.

공휴일 날짜는 얼마나 오래 캐시해야 하나요?

현재 연도는 매월 갱신하고 다음 연도는 게시되면 조회하세요. 공휴일 캘린더는 변경이 드물어 갱신 사이에는 연간 집합을 재사용할 수 있습니다. 앱이 자주 재시작한다면 해당 집합을 연도와 함께 파일이나 데이터베이스 테이블에 영구 저장하고, 저장한 집합도 매년 갱신하세요.

실패 응답은 캐시하지 마세요. 두 스크립트 모두 공휴일 날짜를 저장하기 전에 실패 응답을 처리합니다. 캘린더 개정은 Basic 또는 Pro 웹훅 및 스트림의 holiday.calendar.revised 이벤트로 알림을 받을 수 있습니다.

날짜에는 어느 시간대를 사용해야 하나요?

해당 시장의 현지 시간대에 따른 날짜를 사용하세요. UTC 자정의 날짜는 미주 지역에서 전날일 수 있으므로 함수에 전달하는 날짜를 확인해야 합니다. 공휴일 집합에는 날짜 문자열이 저장되어 있고 사용한 문자열에 따라 포함 여부가 결정되므로, 두 스크립트에 전달하기 전에 해당 시장의 날짜를 확정하세요.

Python 함수는 date를 받습니다. JavaScript 함수는 ISO 날짜 문자열을 받아 해당 연도로 공휴일 집합을 선택합니다. 두 함수 모두 시장 시간대 인수는 받지 않습니다.

해당 연도가 아직 게시되지 않았다면 어떻게 하나요?

API가 404 calendar_not_published를 반환하면 주말만 기준으로 판단하고 이를 로그에 남기세요. 이 대체 처리에서는 토요일과 일요일은 계속 비영업일이며, 평일은 공휴일 조회 없이 영업일로 처리됩니다. 공휴일 캘린더를 사용할 수 없으므로 평일의 결과는 주말 규칙만으로 결정됩니다.

두 함수 모두 실패 응답에 대해 오류를 발생시킵니다. 앱에서 해당 오류를 처리하는 곳에 주말만 기준으로 판단하는 대체 처리를 추가하고, 미게시 응답은 공휴일 캐시에 넣지 마세요. 오류 레퍼런스는 API 오류를 확인하세요.

실습 예시: 2026년 추수감사절 주간

2026년 11월 26일 목요일과 2026년 USA 캘린더부터 확인하세요. 평일이므로 공휴일 집합에 포함되는지에 따라 결과가 결정됩니다. 미국 추수감사절이므로 영업일 결과는 False입니다.

이어서 2026년 11월 27일 금요일을 확인하세요. 평일이고 공휴일 집합에 없으므로 결과는 True입니다. 2026년 11월 28일 토요일은 평일 조건을 충족하지 않아 공휴일 조회 없이 False를 반환합니다.

2026-11-26 Thu False
2026-11-27 Fri True
2026-11-28 Sat False

false true false