달력 API 레퍼런스
REST 및 MCP를 통한 연간 공휴일, 날짜 조회 및 다음 공휴일 요청입니다.
라이브 공개 베타
아래 게시된 국가-연도에 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 서식입니다. 국가 및 날짜/연도 매개변수는 필수입니다. 선택적 범위 필터로 공휴일 범주를 선택합니다. 페이지 매김이나 하위 지역 필터는 없습니다.
공유 공휴일 객체
| 필드 | 유형 | 의미 |
|---|---|---|
date | 날짜 문자열 | 수집 타임스탬프가 아닌 현지 달력 날짜입니다. |
name | 문자열 | 영문/표시 이름, 1~256자입니다. |
local_name | 문자열 또는 null | 가능한 경우 현지 이름, 1~256자입니다. |
subdivision_codes | 문자열 배열 | GB-SCT와 같이 해당 국가에 속하는 고유 정렬 코드입니다. |
nationwide | 불리언 | true에는 빈 하위 지역 목록이 필요하고 false에는 비어 있지 않은 목록이 필요합니다. |
scope | 문자열 | national_public, bank, federal_government 또는 collective_leave와 같은 공휴일 범주입니다. |
observed | 불리언 또는 null | 관측/대체 상태를 명시합니다. Null은 false가 아니라 알 수 없음을 의미합니다. |
일반 공휴일 객체에는 7개 필드가 모두 포함됩니다. 각 응답에는 빈 날짜 결과에도 범위, nationwide 및 subdivision_codes를 포함한 데이터 범위 선언이 포함됩니다. 요청 ID와 할당량은 헤더에 유지됩니다. 성공 본문에는 출처 URL과 수집 확인 시각이 포함되지 않습니다.
데이터 범위 및 제한
| 국가 | 2026 | 2027 | 게시된 범위 |
|---|---|---|---|
ARG | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
AUS | 사용 가능 | 사용 가능 | 뉴사우스웨일스 한정: 지역 공휴일 및 은행 공휴일 |
BRA | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
CAN | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
CHN | 사용 가능 | 아직 이용할 수 없음 | 국가 공휴일 휴무이며 대체 근무일은 제외됩니다 |
FRA | 사용 가능 | 사용 가능 | 일반적인 국가 법정 공휴일이며 지역별 추가 공휴일은 제외됩니다 |
DEU | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
IND | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
IDN | 사용 가능 | 아직 이용할 수 없음 | 국가 공휴일과 단체 휴가를 별도로 표시합니다 |
ITA | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
JPN | 사용 가능 | 사용 가능 | 국가 공휴일 |
MEX | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
KOR | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
RUS | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
SAU | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
ZAF | 아직 이용할 수 없음 | 사용 가능 | 국가 공휴일이며 학교에만 적용되는 공휴일은 제외됩니다 |
TUR | 아직 이용할 수 없음 | 아직 이용할 수 없음 | 출처 검토 중 |
GBR | 사용 가능 | 사용 가능 | 잉글랜드·웨일스, 스코틀랜드, 북아일랜드의 공휴일 |
USA | 사용 가능 | 사용 가능 | 연방 공무원 공휴일 및 대체 휴일이며 주 공휴일은 제외됩니다 |
목표는 계속 19개 국가입니다. 이용 가능한 항목은 명시된 범위만 설명하며 모든 지역 또는 업종 공휴일을 다루지 않습니다. 연도 검증은 1900~2200을 허용하지만 이것이 과거 데이터 범위를 의미하지는 않습니다.
게시된 연도에는 1~400개의 이벤트가 포함됩니다. 누락되었거나 철회된 커버리지는 다음을 반환합니다: 503 calendar_coverage_unavailable 날짜 조회가 빈 배열을 반환할 수 있는 경우는 해당 연도가 게시된 때뿐입니다. 공휴일이라는 사실만으로 은행이나 거래소의 휴장을 증명할 수는 없습니다.
성공한 호출은 빈 날짜 결과를 포함해 공유 월간 요청 1회를 소비합니다. 오류는 월간 할당량을 소비하지 않지만 단기 속도 제한은 계속 적용됩니다. 공유 오류 및 할당량 계약 읽기.