한국어 · English

🇰🇷 Korean Public Holidays API

Accurate South Korean public holidays — including substitute holidays, temporary holidays and election days — as free JSON. No sign-up, no API key.

API docs GitHub npm PyPI

Why this API

Substitute holidaysKorea moves holidays that fall on weekends — with different rules per holiday. This API applies them for you.

Verified weeklyEvery week the data is compared with the official KASI dataset; mismatches open a GitHub issue automatically.

2015 – 2027Including Labor Day and Constitution Day, which became public holidays in 2026.

Business days"3 business days from now", payday adjustment, Nth business day of a month.

Quick start

curl "https://korea-holidays-api.greenteapie2023.workers.dev/holidays?year=2027"

{
  "year": 2027,
  "holidays": [
    { "date": "2027-01-01", "name": "신정", "nameEn": "New Year's Day", "type": "national" },
    { "date": "2027-02-06", "name": "설날 전날", "nameEn": "Day before Seollal", "type": "national" },
    ...
  ]
}

Endpoints

Endpoint	What it does
`/holidays?year=2027`	Holidays of a year (filter by `month`, `type`)
`/holidays/check?date=2027-09-15`	Is it a holiday / business day?
`/holidays/next?count=3`	Upcoming holidays with days remaining
`/business-days/add?date=…&days=3`	Add (or subtract) business days
`/business-days/count?from=…&to=…`	Count business days in a range
`/business-days/adjust?date=…&rule=previous`	Move a payday off a holiday
`/business-days/nth?year=2027&month=1&n=-1`	Nth (or last) business day of a month
`/long-weekends?year=2027`	Long weekends
`/vacation-tips?year=2027&leaveDays=2`	Best days to take leave for the longest break
`/calendar.ics?lang=en`	Subscribe in Google / Apple Calendar

Options for business-day endpoints: weekend=sun (Saturday is a workday), include= extra days off, exclude= days you work anyway.

Calendar feed

Add this URL in Google Calendar → Other calendars → From URL. Holiday names are in English.

https://korea-holidays-api.greenteapie2023.workers.dev/calendar.ics?lang=en

Libraries

npm install korea-holidays
pip install korea-holidays

import { addBusinessDays, isHoliday } from 'korea-holidays'
isHoliday('2027-09-15')            // true (Chuseok)
addBusinessDays('2027-09-13', 2)   // '2027-09-20'

For AI assistants (MCP)

Connect Claude or any MCP client so it stops guessing Korean holiday dates:

https://korea-holidays-api.greenteapie2023.workers.dev/mcp

Claude Code: claude mcp add --transport http korea-holidays https://korea-holidays-api.greenteapie2023.workers.dev/mcp