문서
특정 날짜의 공휴일
특정 현지 캘린더 날짜에 해당하는 공휴일 중 게시된 항목을 모두 조회합니다.
요청
게시된 국가별 연도 데이터는 Narwhal 키로 이용할 수 있습니다. 범위와 적용 대상 확인 —날짜를 요청하기 전에 확인하세요.
GET /v1/calendars/holidays/{country}/on/{date}curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/on/2026-08-17" \
-H "Authorization: Bearer $NARWHAL_API_KEY"매개변수
| 이름 | 유형 | 규칙 |
|---|---|---|
country | 문자열 | 필수 경로 값입니다. IDN과 같은 지원되는 대문자 ISO alpha-3 코드 하나입니다. |
date | 날짜 문자열 | 필수 경로 값 YYYY-MM-DD이며 연도는 1900~2200입니다. |
scope | 문자열 | 선택 쿼리 필터: national_public, regional_public, bank, federal_government, central_government, collective_leave, public_sector 또는 private_sector. 생략하면 게시된 모든 범주를 반환합니다. 해당 국가와 연도에 게시된 데이터가 없는 범위를 지정하면 404 calendar_not_published를 반환합니다. 응답의 coverage에는 해당 범위만 나열됩니다. |
하위 지역 필터나 페이지 매김이 없습니다. MCP 입력 객체는 추가 필드를 거부합니다.
예시 응답
{
"country": "IDN",
"coverage": [
{
"scope": "collective_leave",
"subdivision_codes": []
},
{
"scope": "national_public",
"subdivision_codes": []
}
],
"holidays": [
{
"date": "2026-08-17",
"name": "Independence Day",
"local_name": "Proklamasi Kemerdekaan",
"subdivision_codes": [],
"scope": "national_public"
}
]
}일치하는 모든 이벤트를 반환합니다. holidays 배열이 비어 있으면 게시된 완전한 연간 캘린더에서 일치하는 이벤트가 없다는 뜻입니다. 은행이나 거래소가 열려 있다는 증거는 아닙니다. 게시되지 않은 국가·연도는 404 calendar_not_published를 반환하며, 읽기에 실패하면 503을 반환합니다.
공유 공휴일 필드. 모든 이벤트에는 전국 또는 지역 단위의 적용 범위가 명시되어 있습니다.
대응하는 MCP 호출
인증을 포함하여 보낼 요청: POST /mcp 다음과 함께 Accept: application/json, text/event-stream.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "calendars_get_holidays_on_date",
"arguments": {
"country": "IDN",
"date": "2026-08-17"
}
}
}성공한 결과의 오류 상태: isError: false, 동일한 응답을 담는 필드: structuredContent, 직렬화된 JSON을 담는 필드: content[0].text. 도메인 오류의 오류 상태: isError: true.
오류 및 할당량
입력이 잘못되면 400, 키가 없거나 유효하지 않으면 401을 반환합니다. 등록되지 않은 경로는 404를 반환합니다. 요청 빈도 한도나 할당량을 초과하면 429를 반환합니다. 요청한 국가·연도의 캘린더가 게시되지 않았으면 404 calendar_not_published, 현재 캘린더를 안전하게 제공할 수 없으면 503 calendar_coverage_unavailable.
연도, 날짜 또는 범위가 요금제의 과거 데이터 범위(Free 12개월, Basic 5년, Pro 전체)보다 이전이면 403 plan_upgrade_required를 반환합니다.
성공한 호출 하나는 이벤트 수나 조회 연도와 관계없이 월간 요청 1회를 소비합니다. 오류는 월간 할당량을 소비하지 않습니다. 공유 오류 세부 정보.