한국 공휴일 JSON API

한국 공휴일을 JSON 으로 받을 수 있나요? 네. 휴일모아는 2026~2028년 한국 관공서 공휴일을 인증 키 없이 받을 수 있는 정적 JSON 으로 제공합니다. 각 공휴일에 한국어 이름과 name_en(영문 이름)이 함께 들어 있어 영문만 쓰는 곳에서도 바로 쓸 수 있습니다.

엔드포인트

용도경로 (GET)
전체 공휴일/holidays.json
연도별 공휴일/api/holidays/{year}.json (예: /api/holidays/2026.json)

보유 연도: 2026, 2027, 2028. 보유하지 않은 연도는 파일이 없어 404 입니다. 응답 Content-Type 은 application/json 입니다.

공휴일 필드

필드타입설명
datestring공휴일 날짜 "YYYY-MM-DD"
namestring한국어 이름 (예: 신정)
name_enstring영문 관용 표기 (예: New Year's Day)
typestringpublic(공휴일) · substitute(대체공휴일) · election(선거일)
weekdaynumber요일 0=일 … 6=토
verifiedboolean날짜 확정 여부(미검증이면 false)

메타 필드

필드설명
country국가 코드 "KR"
source데이터 출처/라이선스 안내
checkedAt데이터 확인일
note / note_ko불완전성 고지(영문 / 한국어)
year범위 — 연도별이면 그 해, 전체면 "all"
years보유 연도 목록
verified이 범위 전체가 확정이면 true

예시 응답 (/api/holidays/2026.json 발췌)

{
  "country": "KR",
  "source": "Korea Astronomy and Space Science Institute almanac (월력요항); 관공서의 공휴일에 관한 규정",
  "checkedAt": "2026-11-05",
  "note": "2028 holidays were not cross-checked against the original 2028 almanac (lunar dates verified via conversion and third-party calendars). 2027 and 2028 election days and temporary holidays are not included.",
  "note_ko": "2028년 공휴일은 2028 월력요항 원문 미대조(음력 날짜는 변환 알고리즘·해외 달력 교차 확인). 2027·2028년 선거일·임시공휴일 미반영",
  "year": 2026,
  "years": [
    2026,
    2027,
    2028
  ],
  "verified": true,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "신정",
      "name_en": "New Year's Day",
      "type": "public",
      "weekday": 4,
      "verified": true
    },
    {
      "date": "2026-02-16",
      "name": "설날 연휴",
      "name_en": "Seollal Holiday",
      "type": "public",
      "weekday": 1,
      "verified": true
    }
  
    // … 생략 …
  ]
}

출처·갱신 주기·라이선스

  • 출처: Korea Astronomy and Space Science Institute almanac (월력요항); 관공서의 공휴일에 관한 규정. 날짜·이름은 공개된 사실값이며, 저작권 있는 원문 테이블을 그대로 복제하지 않습니다.
  • 갱신 주기: 월력요항 발표·법령 개정이 반영될 때 데이터를 갱신하고 checkedAt(2026-11-05)을 올립니다.
  • 미래 연도 고지: 월력요항 발표 범위를 넘는 미래 연도는 변동될 수 있습니다. 음력·대체·선거·임시공휴일 중 미확정 항목은 verified:false 로 표시합니다. (2028년 공휴일은 2028 월력요항 원문 미대조(음력 날짜는 변환 알고리즘·해외 달력 교차 확인). 2027·2028년 선거일·임시공휴일 미반영)
  • 사용: 사실 데이터이므로 자유롭게 쓸 수 있습니다. 출처 표기를 권장합니다.

브라우저에서 바로 fetch 해도 되나요? (CORS)

이 API 는 S3 에 올라간 정적 .json 파일이라 사이트 코드로는 Access-Control-Allow-Origin 같은 응답 헤더를 붙일 수 없습니다. CORS 헤더 설정은 배포 인프라(CloudFront 응답 헤더 정책 / S3 CORS)의 몫입니다.

  • 호스팅에서 CORS 헤더가 설정된 경우: 브라우저에서 직접 fetch 가 됩니다.
  • 설정 전·불가한 경우: 브라우저 직접 fetch 가 CORS 로 막힐 수 있으니 서버 사이드 fetch, 빌드 시 다운로드, 또는 프록시 경유를 권장합니다.

자주 묻는 질문

한국 공휴일을 JSON 으로 받을 수 있나요?

네. 휴일모아는 2026~2028년 한국 관공서 공휴일을 정적 JSON 으로 제공합니다. 전체는 https://hyuilmoa.com/holidays.json, 연도별은 https://hyuilmoa.com/api/holidays/{year}.json 을 그대로 GET 하면 됩니다. 각 공휴일에 한국어 이름(name)과 영문 이름(name_en)이 함께 들어 있어 영문만 쓰는 곳에서도 바로 쓸 수 있습니다.

인증 키가 필요한가요? 요청 제한이 있나요?

아니요. 키·토큰·회원가입 없이 누구나 GET 으로 받을 수 있는 정적 파일입니다. 서버 로직이 없어 호출 제한(rate limit)도 없습니다.

브라우저에서 바로 fetch 해도 되나요?

정적 파일이라 사이트 코드로는 CORS 응답 헤더를 붙일 수 없습니다. 호스팅(CloudFront/S3)에서 Access-Control-Allow-Origin 을 설정하면 브라우저에서 직접 fetch 가 가능하고, 그렇지 않으면 서버 사이드 fetch·빌드 시 다운로드·프록시 경유를 권장합니다.

미래 연도 데이터는 믿어도 되나요?

월력요항 발표 범위를 넘는 미래 연도는 변동될 수 있습니다. 특히 음력(설날·추석·부처님오신날)·대체공휴일·선거일·임시공휴일은 확정 전까지 verified:false 로 표시합니다. 응답의 note/checkedAt 으로 데이터 상태를 확인하세요.

공휴일 달력이 필요하면 2028년 공휴일 달력, 캘린더 앱 구독은 ICS 파일을 보세요.