문서
공휴일 나열
특정 국가의 특정 연도에 대해 게시된 캘린더 전체를 조회합니다.
요청
게시된 국가별 연도 데이터는 Narwhal 키로 이용할 수 있습니다. 범위와 적용 대상 확인 —날짜를 요청하기 전에 확인하세요.
GET /v1/calendars/holidays/{country}/{year}curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026" \
-H "Authorization: Bearer $NARWHAL_API_KEY"매개변수
| 이름 | 유형 | 규칙 |
|---|---|---|
country | 문자열 | 필수 경로 값입니다. IDN과 같은 지원되는 대문자 ISO alpha-3 코드 하나입니다. |
year | 정수 | 필수 경로 값이며 1900~2200을 포함합니다. 이 범위가 과거 데이터 범위를 보장하지는 않습니다. |
version_id | UUID 문자열 | 공휴일 이벤트의 resource_version에서 가져오는 선택 쿼리 값입니다. 소스 이용 권한이 유지되는 동안 해당 국가·연도의 불변 캘린더를 읽습니다. 생략하면 현재 캘린더를 읽습니다. 알 수 없는 버전은 404 calendar_not_published를, 읽기 실패는 503을 반환합니다. |
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"
}
]
}게시된 연도 전체를 날짜와 이름 순으로 정렬하고 안정적으로 동률을 처리해 반환합니다. 같은 날의 서로 다른 공휴일은 별도로 유지됩니다. 페이지 매김은 없습니다. 예시는 완전한 캘린더이 아닌 이벤트 하나를 보여줍니다.
공유 공휴일 필드. 모든 이벤트에는 전국 또는 지역 단위의 적용 범위가 명시되어 있습니다.
대응하는 MCP 호출
인증을 포함하여 보낼 요청: POST /mcp 다음과 함께 Accept: application/json, text/event-stream.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "calendars_list_holidays",
"arguments": {
"country": "IDN",
"year": 2026
}
}
}성공한 결과의 오류 상태: 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회를 소비합니다. 오류는 월간 할당량을 소비하지 않습니다. 공유 오류 세부 정보.