Korean public holiday JSON API

Can I get Korean public holidays as JSON? Yes. Hyuilmoa serves South Korean government public holidays for 2026–2028 as static JSON you can fetch without an API key. Every holiday carries both a Korean name and an English name_en, so it works in English-only apps.

Endpoints

PurposePath (GET)
All holidays/holidays.json
One year/api/holidays/{year}.json (e.g. /api/holidays/2026.json)

Years available: 2026, 2027, 2028. Years that are not available return 404 (no file). The response Content-Type is application/json.

Holiday fields

FieldTypeMeaning
datestringHoliday date "YYYY-MM-DD"
namestringKorean name (e.g. 신정)
name_enstringEnglish name (e.g. New Year's Day)
typestringpublic · substitute · election
weekdaynumberDay of week 0=Sun … 6=Sat
verifiedbooleanfalse if the date is not yet confirmed

Metadata fields

FieldMeaning
countryCountry code "KR"
sourceData source / license note
checkedAtDate the data was last checked
note / note_koIncompleteness notice (English / Korean)
yearScope — the year, or "all" for the full file
yearsList of years available
verifiedtrue if every entry in this scope is confirmed

Example response (excerpt of /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
    }
  
    // … truncated …
  ]
}

Source, cadence, license

  • Source: Korea Astronomy and Space Science Institute almanac (월력요항); 관공서의 공휴일에 관한 규정. Dates and names are public factual values; the original copyrighted tables are not reproduced verbatim.
  • Update cadence: the data is refreshed when a new almanac or a law change lands, and checkedAt (2026-11-05) is bumped.
  • Future years: years beyond the published almanac range may change. Unconfirmed lunar, substitute, election, and temporary holidays are flagged verified:false. (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.)
  • Usage: factual data, free to use; attribution appreciated.

Can I fetch it directly from the browser? (CORS)

This API is static .json served from S3, so the site code cannot attach response headers such as Access-Control-Allow-Origin. CORS headers are the job of the deployment infrastructure (a CloudFront response-headers policy / S3 CORS configuration).

  • If the host sets CORS headers: a direct browser fetch works.
  • If not: a browser fetch may be blocked by CORS, so prefer a server-side fetch, a build-time download, or a proxy.

FAQ

Can I get Korean public holidays as JSON?

Yes. Hyuilmoa serves Korean government public holidays for 2026–2028 as static JSON. GET https://hyuilmoa.com/holidays.json for all years, or https://hyuilmoa.com/api/holidays/{year}.json for one year. Every holiday carries both a Korean name (name) and an English name (name_en), so you can use it in English-only apps.

Do I need an API key? Is there a rate limit?

No. These are static files you can GET without a key, token, or sign-up. There is no server logic, so there is no rate limit.

Can I fetch it directly from the browser?

Because these are static files, the site code cannot attach CORS response headers. If the hosting layer (CloudFront/S3) sets Access-Control-Allow-Origin, browser fetch works. Otherwise prefer a server-side fetch, a build-time download, or a proxy.

Can I trust future-year data?

Future years beyond the published almanac range may change. Lunar holidays (Seollal, Chuseok, Buddha's Birthday), substitute holidays, election days, and temporary holidays are marked verified:false until confirmed. Check note and checkedAt in the response.

Need a calendar instead? See the 2028 holiday calendar or subscribe via the ICS file.