apipick
[ 레퍼런스 · holidays ]● 1 cr · 120 req/min

공휴일 조회 API

API 호출 한 번으로 100여 국가와 임의 연도의 공휴일을 조회하세요. 완전 로컬 연산 — 외부 데이터 소스도, 레이트 리밋으로 인한 뜻밖의 사고도 없습니다.

100여 국가임의 연도외부 의존성 없음
auth · x-api-key

API 키가 없으신가요?

계정에 로그인하여 API 키를 생성하고 관리하세요.

로그인API 키 관리
[ 02 · integrate ]

통합 가이드

스니펫을 복사하고 API 키를 교체한 뒤 실행하세요. 모든 HTTP 클라이언트에서 작동합니다 — 아래에 cURL, JavaScript, Python 예제가 있습니다.

spec
GET/api/holidays
base
https://www.apipick.com

Get all public holidays for a country and year

매개변수
countrystring필수

ISO 3166-1 alpha-2 country code US

yearinteger선택

4-digit year (defaults to current year) 2026

curl -X GET "https://www.apipick.com/api/holidays" \
  -H "x-api-key: YOUR_API_KEY"
● 200 · 응답
{
  "success": true,
  "code": 200,
  "message": "Holidays retrieved successfully",
  "data": {
    "country": "US",
    "country_name": "United States",
    "year": 2026,
    "total": 11,
    "holidays": [
      {
        "date": "2026-01-01",
        "name": "New Year's Day"
      },
      {
        "date": "2026-01-19",
        "name": "Martin Luther King Jr. Day"
      },
      {
        "date": "2026-02-16",
        "name": "Presidents' Day"
      },
      {
        "date": "2026-05-25",
        "name": "Memorial Day"
      },
      {
        "date": "2026-07-03",
        "name": "Independence Day (observed)"
      },
      {
        "date": "2026-09-07",
        "name": "Labor Day"
      },
      {
        "date": "2026-10-12",
        "name": "Columbus Day"
      },
      {
        "date": "2026-11-11",
        "name": "Veterans Day"
      },
      {
        "date": "2026-11-26",
        "name": "Thanksgiving Day"
      },
      {
        "date": "2026-12-25",
        "name": "Christmas Day"
      }
    ]
  },
  "credits_used": 1,
  "remaining_credits": 99
}

실전 일정 관리를 위해 제작

🏢

HR 일정 관리

여러 국가에 걸쳐 휴가 잔여일, 급여 주기, 근무 교대표를 계산할 때 공휴일을 자동으로 제외하세요.

📈

거래 캘린더

금융 모델과 백테스트에서 비거래일을 건너뛰세요. 결제·청산 윈도우에 영향을 주는 은행 휴일을 식별합니다.

📦

물류 ETA

출발지, 경유지, 도착지 국가의 공휴일을 자동으로 건너뛰어 정확한 배송 예상 시간을 계산하세요.

⚙️

n8n 자동화

n8n이나 Zapier 워크플로에 연결해 시간 민감 작업을 게이팅하세요 — 국경일에는 이메일이나 보고서 발송을 건너뜁니다.

HolidayAPI & Nager.Date 대안

올해 데이터, 미래 연도 계획, 프로덕션 SLA — 무료 등급의 연도 잠금이나 커뮤니티 프로젝트의 신뢰성 리스크 없이.

HolidayAPI
Nager.Date
API Pick ✓
무료 등급전년도만무료 (SLA 없음)가입 시 100 크레딧
올해 데이터유료 요금제만✓✓
미래 연도 데이터유료 요금제만✓ (제한적)✓ 최대 +10년
과거 데이터 (1900년 이후)유료 요금제만부분 지원✓ 1900년부터
프로덕션 SLA유료 요금제만✗ 커뮤니티 프로젝트✓
지원 국가~100~110100+
시작 시 신용카드 불필요✗✓✓
크레딧 / 요청 만료?연간 요금제N/A만료 없음
AI 에이전트 / LLM 지원부분 지원부분 지원✓ 네이티브 JSON

HolidayAPI 무료 등급의 함정

HolidayAPI의 무료 요금제는 의도적으로 전년도 한 해로만 제한됩니다. 올해 공휴일을 조회하거나 2027년 휴가 일정을 미리 계획해야 하나요? 유료 요금제로 업그레이드해야 합니다. 일정 관리나 자동화 용도라면 이 무료 등급은 첫날부터 사실상 쓸모가 없습니다.

Nager.Date의 신뢰성 리스크

Nager.Date는 커뮤니티가 관리하는 오픈소스 프로젝트입니다 — 무료로 쓸 수 있지만 가동률 SLA도, 지원 계약도, 지속적인 가용성 보장도 없습니다. 이를 기반으로 급여 시스템이나 물류 파이프라인을 구축한 팀들은 예기치 못한 다운타임이나 지원 중단으로 곤란을 겪어 왔습니다. 프로토타이핑에는 괜찮지만 프로덕션에는 적합하지 않습니다.

응답 필드

필드타입설명
data.countrystringISO 3166-1 alpha-2 국가 코드 (대문자)
data.country_namestring영문 국가명 전체
data.yearinteger조회한 연도
data.totalinteger해당 연도의 공휴일 수
data.holidaysarray날짜순으로 정렬된 공휴일 객체 목록
data.holidays[].datestringYYYY-MM-DD 형식의 공휴일 날짜
data.holidays[].namestring공휴일의 공식 명칭
credits_usedinteger이 요청으로 차감된 크레딧
remaining_creditsinteger계정에 남은 크레딧
[ 03 · limits ]

요청 제한

스로틀링은 API 키 단위, 60초 슬라이딩 윈도우입니다. 한도에 도달하면 Retry-After 헤더가 포함된 깔끔한 429를 받습니다.

요청 속도

120req/min

API 키별, 엔드포인트별. 60초 슬라이딩 윈도우.

동시성

3concurrent

API 키당 동시에 처리 중인 최대 요청 수.

응답 헤더
X-RateLimit-Limit분당 허용되는 최대 요청 수
X-RateLimit-Remaining현재 윈도우에 남은 요청 수
X-RateLimit-Reset현재 윈도우가 초기화되기까지의 초
Retry-After재시도 전 대기 초 (429일 때만)
● 429 · 요청이 너무 많음
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 120 requests/minute per API key. Retry after 12s.",
  "retry_after": 12
}

자주 묻는 질문

Q: 어떤 국가를 지원하나요?

A: 오픈소스 python-holidays(vacanza) 라이브러리를 통해 100여 국가를 지원합니다. 미국, 영국, 독일, 프랑스, 일본, 중국, 호주, 캐나다, 인도, 브라질을 비롯해 유럽, 아시아, 라틴 아메리카, 아프리카 대부분이 포함됩니다. 유효한 ISO 3166-1 alpha-2 코드(예: US, GB, DE)를 사용하세요.

Q: 과거와 미래로 얼마나 멀리까지 조회할 수 있나요?

A: 1900년부터 미래 10년까지 임의의 연도를 조회할 수 있습니다. 과거 공휴일은 당시 시행되던 규칙을 바탕으로 계산되므로, 오늘날의 규칙을 과거에 투영한 것이 아니라 실제 역사적 기념일을 반영합니다.

Q: 지방/주 공휴일도 포함되나요?

A: 이 엔드포인트는 국가 공휴일만 반환합니다. 주·성·지역별 기념일(예: 미국 주 공휴일, 독일 주(Länder) 공휴일)은 기본 응답에 포함되지 않습니다. 하위 행정 구역 수준의 공휴일 데이터가 필요하면 문의하세요.

Q: AI 에이전트가 이것을 도구로 사용할 수 있나요?

A: 네. 엔드포인트는 두 개의 쿼리 매개변수(country와 year)를 받아 구조화된 JSON 배열을 반환하므로 OpenAI, Claude, LangChain 등 어떤 에이전트 프레임워크의 함수 도구로도 간단하게 정의할 수 있습니다. 여러 국가에 걸쳐 영업일을 추론해야 하는 일정 관리 에이전트에 이상적입니다.

🤖에이전트 스킬

Claude Code와 AI 에이전트에서 Public Holidays 사용하기

공식 Claude Code 스킬을 설치해 AI 코딩 에이전트 안에서 자연어로 100여 국가의 공휴일을 바로 조회하세요 — 정렬된 날짜, 공식 명칭, 개수를 확인할 수 있습니다.

AI 에이전트에게 자연스럽게 물어보세요

›2026년 미국 공휴일은 뭐야?
›올해 일본 공휴일을 모두 나열해 줘
›12월 26일은 영국에서 공휴일이야?

호환 플랫폼

Claude CodeCursorOpenAI CodexManusGoogle AntigravityOpenClaw
apipick-lab /
apipick-public-holidays

APIpick Public Holidays API용 Claude Code 스킬

100여 국가의 공휴일 목록을 날짜순으로 정렬해 공식 영문 명칭과 총 개수와 함께 반환합니다. 1900년부터 10년 앞까지의 연도를 지원합니다.

TypeScript•요청당 1 크레딧•설치 무료
GitHub에서 스킬 보기