holidays

한국의 공휴일, 24절기 및 잡절 정보를 지속적으로 갱신하는 저장소입니다. 선거일이나 대체공휴일이 가끔 추가될 때 있습니다. Cloudflare Worker가 매일 오전 0시에 새로운 정보를 갱신합니다.

다음 형식의 URL을 이용해 데이터를 받아올 수 있습니다.

• https://holidays.dist.be/{year}.json
  • (예) https://holidays.dist.be/2022.json

캘린더 구독 (iCal)

iCal(.ics) 형식도 제공합니다. Google Calendar, Apple Calendar 등에서 URL로 구독하면 데이터 갱신이 자동 반영됩니다.

• https://holidays.dist.be/holidays.ics — 전체 연도(2004~내년)의 공휴일만 (구독 추천)
• https://holidays.dist.be/all.ics — 전체 연도의 공휴일·기념일·24절기·잡절 전부

Google Calendar 기준: 설정 → 캘린더 추가 → URL로 추가에 위 주소를 입력하면 됩니다. 구독 캘린더는 주기적으로(약 12~24시간마다) 자동 갱신됩니다.

데이터 형식

JSON 파일의 형식은 다음 타입스크립트의 JSON 상수를 따릅니다.

declare const JSON: DateInfo[];

enum DateKind {
  Holiday = 1, // 공휴일 - (예) 설날, 대통령선거일, 추석 (대체공휴일) ..
  Anniversary = 2, // 기념일 - (예) 스승의 날, 국군의 날 ..
  SolarTerms = 3, // 24절기 - (예) 입춘, 경칩 ..
  Sundry = 4, // 잡절 - (예) 정월대보름, 초복, 중복 ..
}

interface DateInfo {
  date: string; // YYYY-MM-DD
  name: string; // 이름
  holiday: boolean; // 공휴일 여부
  remarks: string | null;
  kind: DateKind;
  time: string | null; // HH:mm (only SolarTerms)
  sunLng: number | null; // only SolarTerms
}

명칭에 대하여

같은 날짜라도 시점에 따라 공식 명칭이 다른 경우, 데이터는 해당 연도 당시의 공식 명칭을 그대로 사용합니다.

• 석가탄신일 (2017년까지) → 부처님오신날 (2018년부터): 관공서의 공휴일에 관한 규정 개정으로 개칭
• 근로자의 날 (2025년까지) → 노동절 (2026년부터): 2025년 법 개정으로 개칭 및 공휴일 지정
• 그 외 저축의 날 → 금융의 날, 체육의 날 → 스포츠의 날 등 기념일 개칭도 동일하게 당시 명칭을 유지합니다.

다음 명칭은 연도별 표기 편차를 없애기 위해 표준화합니다.

• 신정, 1월1일 → 새해
• 기독탄신일 → 크리스마스
• 대체공휴일 → {원본 공휴일 이름} (대체공휴일) (예: 추석 (대체공휴일))
• 선거일 → 회차를 포함한 공식 명칭 (예: 제22대 국회의원선거, 제9회 전국동시지방선거)
• 개칭이 아닌 단순 공백 표기 차이는 최신 공식 표기로 통일 (예: 5·18 민주화운동기념일, 5·18 민주화운동 기념일 → 5·18민주화운동 기념일)

활용중인 프로젝트

• NPM @kokr/date: Javascript나, Typescript에서 활용하기 쉽게 패키지로 만들었습니다. 패키지 업데이트 없이도 항상 최신 정보의 날짜 데이터를 사용할 수 있습니다.

데이터 출처

데이터는 공공데이터 포털의 한국천문연구원 특일 정보를 이용하였습니다.