hyunbinseo / holidays-kr

대한민국 공휴일을 가공한 자료

대한민국의 공휴일

과학기술정보통신부에서 발표한 월력요항¹을 csv, json, ics 형식으로 가공한 자료입니다. 기념일은 이곳에서 확인합니다.

제작 동기

• 애플 캘린더 등 - 대체 공휴일 일정 미제공
• 구글 캘린더 등 - 잘못된 공휴일 정보 제공
• 공공 데이터 포털 - XML만 제공, API 키 강제²

제공 형식

• 캘린더 구독 - 구글³, 애플⁴ 캘린더 등 지원
• 텍스트 파일 - 웹 호스팅 제공, 다운로드 지원
• 자바스크립트 패키지 - ESM 및 CJS 지원

주요 특징

• 명칭은 공휴일에 관한 법률을 따릅니다. (기독탄신일 등)
• 공휴일이 아닌 국경일은 포함하지 않습니다. (제헌절 등)
• 지방 공휴일은 포함하지 않습니다. (4·3희생자추념일 등)
• 제공되는 csv 파일은 Google 캘린더 형식을 따릅니다.
• 제공되는 ics 파일은 iCalendar 표준을 따릅니다.

공유 캘린더

https://holidays.hyunbin.page/basic.ics 주소로 새로운 캘린더를 구독합니다.

Warning

위 주소를 직접 공유하는 것을 금합니다. holidays.hyunbin.page를 공유합니다.

Note

Google Calendar에 변경사항이 표시되려면 최대 12시간이 걸릴 수 있습니다.

텍스트 파일

생성된 모든 텍스트 파일은 public 디렉터리에 위치합니다.

./public
├── basic.ics   # 모든 연도 (2022년~)
├── basic.json  # 모든 연도 (2022년~)
├── 2022.csv    # 특정 연도
├── 2022.ics    # 특정 연도
├── 2022.json   # 특정 연도
├── 2023.csv
├── 2023.ics
├── 2023.json
└── (하략)

위 파일들은 holidays.hyunbin.page에 게시되어 있습니다.

# (예시) 다음 파일은
./public/basic.json

# 다음 URL에서 확인할 수 있습니다.
https://holidays.hyunbin.page/basic.json

Footnotes

1. 월력요항은 달력 제작의 기준이 되는 자료입니다. 천문법과 천문법 시행령에 따라 작성되어 관보에 게재됩니다. ↩

2. 회원가입, 본인인증, API 활용 신청을 해야만 사용할 수 있습니다. 비밀 키가 사용되므로 클라이언트 코드에서 사용할 수 없습니다. ↩

3. 다른 사람의 Google Calendar 구독하기 문서를 참고합니다. (링크를 사용하여 공개 캘린더 추가하기) ↩

4. iCloud 캘린더 구독 사용하기 문서를 참고합니다. ↩

holidays-kr's Issues

"SERVICE_KEY_IS_NOT_REGISTERED_ERROR"

깃허브에 올라온 내용이 npm 모듈에 반영이 안 된 것 같네요, 저 서비스 키는 어디서 발급받나요?

2023년도 대체공휴일 수정

인사혁신처는 이 같은 내용을 담은 '관공서의 공휴일에 관한 규정' 개정안(대통령령)을 오는 16일부터 입법예고 한다고 15일 밝혔다.

다음 달 5일까지인 입법예고 기간에 인사처는 대체공휴일 지정에 관한 국민 의견을 받을 예정이다. 법제처 심사, 차관·국무회의, 대통령 재가를 거치면 관보에 정식 공포된다.

큰 이변이 없다면 다음 달 중으로 대통령 재가까지 완료돼 올해 부처님오신날부터 적용된다. — 연합뉴스

랜딩 페이지 리다이렉트 오류 (Cloudflare)

/ 경로 리다이렉트가 오작동하는 상황

• 예상: https://github.com/hyunbinseo/holidays-kr#문제-상황
• 실제: https://github.com/hyunbinseo/holidays-kr#문제-상황#문제-상황

참고 자료

• Trace result, WhereGoes
• Cloudflare Community

날짜를 전달하면 공휴일인지 판단하는 함수 제공

Map 데이터가 있는 경우, 이를 활용해 동적¹ 공휴일까지 확인

없을 경우 공휴일에 관한 법률의 정적 공휴일에 해당하는지만 확인

Footnotes

1. 대체 공휴일, 임기 만료에 의한 선거의 선거일 등 ↩

기념일 커스텀 지원

안녕하세요.
혹시 기념일 명칭에 대해서 커스텀하게 설정할 수 있도록 지원이 가능할까요?
query string으로 key-value 값으로 받아서 지원하면 어떨까 싶어서요.

{url}?12-25=아무것도아닌날&01-01=첫날

단일 일자, 다중 공휴일 지원

2025년 어린이날, 부처님 오신 날은 모두 5월 5일입니다.

현재 데이터 구조에선 단일 일자에 다중 공휴일을 지정할 수 없습니다.

export const y2025 = new Map([
  // ...
  ['2025-05-05', '어린이날'],
  ['2025-05-05', '부처님 오신 날'],
  // ...
]) satisfies Year;

ICS 파일에 차년도 공휴일 사전 입력

현시점 기준 2023년 공휴일만 정상적으로 표기되는데, 보통 휴가일정 같은걸 생각하면 최소 내년까지는 표기되면 좋을거 같은데 기간을 확대하실 계획이 있나요?

월력요항이 발표된 후에 ICS 파일을 작성하면 차년도 공휴일 확인에 어려움이 있음

Improve TypeScript types

Analysis of @hyunbinseo/[email protected]

---

Masquerading as CJS

Import resolved to a CommonJS type declaration file, but an ESM JavaScript file.

Used fallback condition

Import resolved to types through a conditional package.json export, but only after failing to resolve through an earlier condition. This behavior is a TypeScript bug. It may misrepresent the runtime behavior of this import and should not be relied upon.

	"@hyunbinseo/holidays-kr"
node10	✅
node16 (from CJS)	✅ (CJS)
node16 (from ESM)	Masquerading as CJS Used fallback condition
bundler	Used fallback condition

제안

안녕하세요.
만들어주신 대한민국 공휴일을 잘 사용하고 있습니다.
한가지 부탁드리고 싶은 것이 있습니다.
공휴일 달력외에 국가기념일 캘린더도 만들어 주실 수 있을까 해서요.
데이터는 https://www.mois.go.kr/chd/sub/a05/feteDay/screen.do 여기에 있네요.

우려되는 점은 "국경일"과 "기념일"이 휴일인 경우도 있고 아닌 경우도 있어서 똑 같은 내용이 2중으로 노출되는 현상이 있을 것 같아요.
그래서 2가지 캘린더가 필요할 것 같아요.

1. 대한민국 국경일+기념일 (공휴일 포함)
2. 대한민국 국경일+기념일 (공휴일 제외)

[스펙문의] 요청 헤더 user-agent필드에 java/1.x 형태로 설정된 경우, 403Forbidden 발생

안녕하세요
자바로 ics파일 조회해서 파싱하는 로직을 작성하다가, 403Forbidden 이 발생하여 이슈 남깁니다.

        
         HttpURLConnection connection;
        try {
            URL url = new URL("https://holidays.hyunbin.page/basic.ics");
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.connect();
         } // 생략

jdk "1.9" 버전을 쓰고 있어서, 위 요청 시 헤더값 user-agent 필드에 Java/1.9이 셋팅되었을 것 같은데요~
이게 원인일까 싶어서, Java/8, Java/1.9, Java/11 로 바꿔가며 테스트해보았더니, 아래와 같은 결과가 나왔습니다.

Java/8: 200 ok
Java/1.9: 403 forbidden
Java/11: 200 ok

혹시 User-agent에 Java/1.x 가 인입되면, 403Forbidden 이 반환되는게 의도된 것일까요?

대체공휴일 안내오류 (석가탄신일)

안녕하세요, 클량에서 공휴일 정보를 보고 구글 캘린더를 버리고, 개발자님의 캘린더를 활용하고 있습니다.

두둥!! 그런데, 구글 캘린더의 대체공휴일 오류(23년 10월 2일이 추석 대체공휴일이라고 표기)는 수정이 되었는데...
개발자님의 캘린더는 대체공휴일 오류 (23년 5월 29일이 석가탄신일 대체공휴일이라고 표기) 가 있네요.

'공휴일에 관한 법률'은 공휴일이 주말과 겹치면 대체공휴일을 적용하도록 돼 있지만, 크리스마스와 석가탄신일은 대체공휴일 대상에 포함되지 않습니다.

인사혁신처에서 대체공휴일 확대를 추진한다고 하나, 현재 기준으로는 석가탄신일 대체공휴일은 잘못된 정보이니 서둘러 수정하시는게 좋을 듯 합니다.

감사합니다.