공휴일 API 레퍼런스

라이브 공개 베타

아래 게시된 국가-연도에 Narwhal API 키를 사용하세요. REST와 MCP는 동일한 범위와 할당량을 공유합니다. 누락된 데이터 범위는 명시적 오류를 반환하며 예시는 설명용입니다.

세 가지 작업

레퍼런스	GET 엔드포인트	MCP 도구
공휴일 나열	`/v1/calendars/holidays/{country}/{year}`	`calendars_list_holidays`
특정 날짜의 공휴일	`/v1/calendars/holidays/{country}/on/{date}`	`calendars_get_holidays_on_date`
다음 공휴일	`/v1/calendars/holidays/{country}/next?from_date={from_date}`	`calendars_get_next_holiday`

대문자 국가 코드를 사용하세요. 예: IDN ; 현지 캘린더 날짜의 형식: YYYY-MM-DD 형식입니다. country 및 date/year 매개변수는 필수입니다. 선택적 scope 필터로 공휴일 범주를 선택합니다. 페이지 매김이나 하위 지역 필터는 없습니다.

공유 공휴일 객체

필드	유형	의미
`date`	날짜 문자열	수집 타임스탬프가 아닌 현지 캘린더 날짜입니다.
`name`	문자열	영문/표시 이름, 1~256자입니다.
`local_name`	문자열	현지 이름이 있으면 1–256자로 반환합니다. 없으면 생략합니다.
`subdivision_codes`	문자열 배열	GB-SCT와 같이 해당 국가의 행정 구역을 나타내는 코드로, 중복 없이 정렬되어 있습니다. 빈 배열은 전국에 적용됨을 뜻합니다.
`scope`	문자열	national_public, bank, federal_government 또는 collective_leave와 같은 공휴일 범주입니다.
`observed`	불리언	실제 휴일 적용 여부 또는 대체 공휴일 여부를 명시합니다. 알 수 없으면 생략합니다. 알 수 없다는 것은 false를 뜻하지 않습니다.

공휴일 객체에는 항상 date, name, scope, subdivision_codes가 포함됩니다. 날짜 조회 결과가 비어 있어도 각 응답에는 scope와 subdivision_codes를 명시하는 데이터 범위 정보가 포함됩니다. 요청 ID와 할당량은 헤더에 포함됩니다. 성공 응답 본문에는 출처 URL과 수집 확인 시각이 포함되지 않습니다.

데이터 범위 및 제한

게시된 API 데이터 범위 · 이용 가능하다고 나열되지 않은 국가와 연도는 데이터 범위를 이용할 수 없음으로 반환됩니다.
국가	2026	2027	게시된 범위
`ARG`	사용 가능	아직 이용할 수 없음	국가 공휴일
`AUS`	사용 가능	사용 가능	뉴사우스웨일스 한정: 지역 공휴일 및 은행 공휴일
`AUT`	사용 가능	사용 가능	국가 공휴일
`BEL`	사용 가능	사용 가능	국가 공휴일
`BRA`	사용 가능	아직 이용할 수 없음	연방정부 공휴일. 선택 휴무와 부분 휴무 제외
`CAN`	사용 가능	사용 가능	연방 규제를 받는 민간 부문 고용주에게 적용되는 전국 법정 기준. 주별 캘린더과 연방 공무원 캘린더은 제외
`CHN`	사용 가능	아직 이용할 수 없음	국가 공휴일 휴무이며 대체 근무일은 제외됩니다
`COL`	사용 가능	사용 가능	국가 공휴일
`CZE`	사용 가능	사용 가능	전국 공휴일. 주요 기념일, 일반 일요일 및 고용주별 휴무는 제외
`DEU`	사용 가능	아직 이용할 수 없음	전국 공통 공휴일. 주별 추가 공휴일 제외
`DNK`	사용 가능	사용 가능	Danmarks Nationalbank 휴무일. 일반 근로자 휴일 캘린더은 아님
`ESP`	사용 가능	아직 이용할 수 없음	국가 공휴일
`EST`	사용 가능	사용 가능	전국 공휴일 및 휴무일. 국가 주요 기념일과 단축 근무일은 제외
`FRA`	사용 가능	사용 가능	전국 공통 법정 공휴일; 지역별 추가 공휴일 제외
`GBR`	사용 가능	사용 가능	잉글랜드·웨일스, 스코틀랜드, 북아일랜드의 은행 공휴일
`HKG`	사용 가능	사용 가능	홍콩 일반 공휴일; 일반 일요일은 제외
`HRV`	사용 가능	사용 가능	국가 공휴일 및 휴무일; 기념일과 종파별 기념일은 제외
`IDN`	사용 가능	사용 가능	국가 공휴일과 단체 휴가를 별도로 표시합니다
`IND`	아직 이용할 수 없음	아직 이용할 수 없음	출처 검토 중
`IRL`	사용 가능	사용 가능	전국 공휴일. 고용주별 대체 휴일과 휴가 권리는 제외
`ITA`	사용 가능	사용 가능	전국 법정 공휴일. 지역 및 고용주별 휴무 제외
`JPN`	사용 가능	사용 가능	국가 공휴일
`KOR`	아직 이용할 수 없음	아직 이용할 수 없음	출처 검토 중
`LTU`	사용 가능	사용 가능	노동법 제123조에 따른 전국 공휴일, 지역 행사 제외
`LUX`	사용 가능	사용 가능	국가 공휴일
`LVA`	사용 가능	사용 가능	전국 공휴일. 기념일과 지역 행사는 제외
`MEX`	사용 가능	사용 가능	전국적으로 적용되는 의무 휴무일(은행, 주·지방자치단체에만 적용되는 휴일 및 업종별 휴무 제외)
`NLD`	사용 가능	사용 가능	전국 공휴일, 휴무 여부는 고용 조건에 따름
`NOR`	사용 가능	아직 이용할 수 없음	Norges Bank 결제 시스템 휴무일. 일반 근로자 휴일 캘린더은 아님
`NZL`	사용 가능	사용 가능	전국 공휴일 및 대체 휴일, 지역 기념일 제외
`PHL`	아직 이용할 수 없음	아직 이용할 수 없음	출처 검토 중
`POL`	사용 가능	사용 가능	전국 공휴일. 일반 일요일, 지역 행사 및 고용주별 휴무는 제외
`PRT`	사용 가능	사용 가능	국가 의무 공휴일; 선택 휴일, 지방자치단체 휴일 및 지역 휴일은 제외
`RUS`	아직 이용할 수 없음	아직 이용할 수 없음	출처 검토 중
`SAU`	아직 이용할 수 없음	아직 이용할 수 없음	출처 검토 중
`SGP`	사용 가능	사용 가능	국가 공휴일 및 출처가 지정한 대체 휴일
`SVK`	사용 가능	사용 가능	국가 공휴일
`SVN`	사용 가능	사용 가능	국가 공휴일 및 휴무일; 휴무일이 아닌 기념일과 지역 휴일은 제외
`SWE`	사용 가능	사용 가능	국가 공휴일
`TUR`	아직 이용할 수 없음	아직 이용할 수 없음	출처 검토 중
`TWN`	사용 가능	사용 가능	정부 기관 캘린더이며 민간 부문 및 시장 휴장은 제외됩니다.
`USA`	사용 가능	사용 가능	연방 공무원 공휴일 및 대체 휴일이며 주 공휴일은 제외됩니다
`ZAF`	사용 가능	사용 가능	국가 공휴일이며 학교에만 적용되는 공휴일은 제외됩니다

이용 가능한 항목은 명시된 범위만 다루며 모든 지역 또는 업종 공휴일을 포함하지 않습니다. 1900~2200년 입력을 허용하지만 과거 데이터 제공을 보장하지는 않습니다.

게시된 한 해의 데이터에는 1~400개의 이벤트가 포함됩니다. 요청한 국가·연도의 캘린더가 게시되지 않았으면 404 calendar_not_published, 현재 캘린더를 안전하게 제공할 수 없으면 503 calendar_coverage_unavailable. 성공한 날짜 조회에서 빈 배열이 반환될 수 있는 경우는 해당 연도 데이터가 게시되어 있을 때뿐입니다. 공휴일이라는 사실만으로 은행의 휴무나 거래소의 휴장을 단정할 수는 없습니다.

연도, 날짜 또는 범위가 요금제의 과거 데이터 범위(Free 12개월, Basic 5년, Pro 전체)보다 이전이면 403 plan_upgrade_required를 반환합니다.

성공한 호출은 날짜 조회 결과가 비어 있어도 공통 월간 할당량에서 요청 1회를 소비합니다. 오류는 월간 할당량을 소비하지 않지만 단기 구간의 요청 빈도 제한은 계속 적용됩니다. 공통 오류 및 할당량 명세 읽기.