특정 날짜가 공휴일인지 확인

API 사용 방법

확인할 국가와 날짜가 있으면 날짜 엔드포인트를 사용하세요. 응답에는 country, coverage, holidays가 포함됩니다. 반환된 각 항목을 별개의 공휴일 날짜로 세지 말고, holidays의 항목을 읽어 적용 범위와 하위 지역을 포함해 어떤 공휴일이 적용되는지 확인하세요.

1. API 키 받기 무료 키를 만들고 환경 변수 NARWHAL_API_KEY에 저장하세요. 키를 Authorization: Bearer YOUR_KEY로 보내세요. curl 명령은 인증 헤더에 해당 환경 변수를 사용합니다.
2. 해당 국가의 날짜 요청 원하는 국가와 날짜를 지정해 GET /v1/calendars/holidays/{country}/on/{date}를 사용하세요. 이 요청은 2026년 12월 28일 영국의 공휴일을 조회합니다.
   curl, 특정 날짜의 공휴일

   복사

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/GBR/on/2026-12-28"

3. 공휴일 목록 읽기 holidays 목록이 비어 있으면 요청한 날짜는 해당 국가의 공휴일이 아닙니다. 목록에 항목이 있으면 해당 날짜의 공휴일을 나타내므로, 필요한 공휴일 캘린더에 해당하는지 판단할 때 각 항목의 범위와 행정구역을 확인하세요.
4. 지정한 날짜 당일 또는 이후의 공휴일 찾기 시작일을 포함해 그날 이후의 공휴일이 필요하면 다음 공휴일 엔드포인트를 사용하세요. 미국의 경우 from_date=2026-10-24로 요청하면 holiday에 2026년 11월 11일 재향군인의 날이 반환됩니다.
   curl, 지정한 날짜 당일 또는 이후의 공휴일

   복사

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/USA/next?from_date=2026-10-24"

요청에서 오류가 반환되면 application/problem+json 응답을 확인하세요. status, code, detail은 오류를 설명하고, request_id는 요청을 식별합니다. 날짜의 공휴일 여부는 성공 응답의 공휴일 목록으로 확인하세요. 오류 응답에는 해당 공휴일 결과가 없습니다.

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

API 요청 없이 날짜를 찾으려면 Narwhal 공휴일 캘린더 (영어)에서 국가를 조회하세요. 필요한 캘린더의 국가부터 선택하세요. 크리스마스 주간 예시에서는 미국과 영국의 결과를 따로 사용하며, 한 국가 내의 지역별 항목도 확인해야 할 수 있습니다.

Excel 또는 Sheets에서 공휴일 날짜 열의 이름을 Holidays로 지정하고 확인할 날짜를 A2에 입력하세요. 수식은 해당 날짜가 공휴일 열에 있는지 확인합니다. 수식은 입력한 날짜 목록에 포함되는지만 확인하므로, 확인하려는 국가의 공휴일 목록을 사용하세요.

=COUNTIF(Holidays, A2)>0

미국 공휴일 목록을 사용하면 수식은 2026년 12월 25일에 TRUE, 2026년 12월 24일에 FALSE를 반환합니다. 이 결과는 Holidays에 있는 공휴일 날짜에 따라 달라지며, 수식 자체가 API에서 국가 캘린더를 요청하지는 않습니다.

목록 포함 여부를 확인할 때는 선택한 목록에 해당 날짜가 있는지만 알면 됩니다. 지역별 항목의 날짜가 같아도 수식으로 포함 여부를 확인할 수 있습니다. 항목이 어느 지역에 적용되는지 판단하려면 목록에 날짜를 넣기 전에 API 응답에서 해당 항목의 행정구역을 확인하세요.

상황별 계산 방법

연간 목록을 사용하려면 코드에 공휴일 확인 추가를 따르세요. 날짜 엔드포인트는 입력한 날짜의 공휴일 여부를 알려주고, 다음 공휴일 엔드포인트는 시작일을 받아 공휴일 날짜를 반환합니다. 특정 날짜가 공휴일인지 확인하려면 요청에 해당 날짜를 넣으세요. 그날 당일 또는 이후에 어떤 공휴일이 있는지 확인하려면 해당 날짜를 from_date로 전달하세요.

응답에 같은 공휴일이 여러 번 나오는 이유는 무엇인가요?

공휴일이 지역마다 다르면 API는 행정구역 그룹별로 항목을 반환합니다. 영국에서 2026년 12월 28일로 대체되는 박싱 데이의 경우 잉글랜드와 웨일스를 묶은 항목, 북아일랜드 항목, 스코틀랜드 항목을 반환합니다.

행정구역 코드는 공동 항목의 경우 GB-ENG와 GB-WLS, 북아일랜드는 GB-NIR, 스코틀랜드는 GB-SCT입니다. 각 항목의 범위는 bank이고 observed: true입니다. 같은 공휴일 날짜에 대한 지역별 항목이므로 이름과 함께 행정구역 그룹을 확인하세요.

observed: true는 무엇을 뜻하나요?

공휴일이 주말과 겹칠 때 해당 날짜가 대체 휴일임을 뜻합니다. 박싱 데이인 2026년 12월 26일은 토요일이므로 은행 공휴일은 2026년 12월 28일 월요일입니다.

이 예시에서 은행 공휴일 캘린더에 포함되는지 확인할 때는 대체된 은행 공휴일 날짜를 사용하세요. observed 필드는 반환된 날짜가 공휴일의 원래 날짜와 다른 이유를 설명하며, 두 날짜 모두 같은 박싱 데이 예시에 해당합니다.

공동 휴가일은 어떻게 제외하나요?

결과에서 인도네시아의 공동 휴가일을 제외하려면 scope=national_public을 전달하세요. 인도네시아의 공동 휴가인 쿠티 베르사마는 별도의 collective_leave 범위에 포함되므로, 이 필터 없이 요청하면 해당 날짜가 포함될 수 있습니다.

선택 사항인 scope 필터는 결과를 하나의 범위로 제한합니다. 사용할 수 있는 값의 예로는 national_public, bank, federal_government, collective_leave가 있습니다. 반환된 공휴일 항목을 해석하기 전에 필요한 캘린더에 맞는 범위를 선택하세요.

실습 예시: 미국과 영국의 2026년 크리스마스 주간

먼저 미국의 2026년 12월 24일을 확인하세요. 목록이 비어 있으므로 공휴일이 아닙니다. 이어서 같은 국가의 2026년 12월 25일을 확인하면 federal_government 범위의 크리스마스가 나오므로 해당 캘린더에서는 공휴일입니다.

영국의 경우 2026년 12월 25일을 조회하고 bank 범위의 크리스마스 항목을 확인하세요. 이어서 2026년 12월 28일을 조회해 박싱 데이 대체 휴일 항목을 확인하세요. 각 결과를 기록할 때는 국가, 날짜, 범위를 함께 저장하세요.