Holidays
431 dates, 2004–2028, with English names. 1 credit a call. The two endpoints.
Korean holidays cannot be computed
Three of them are lunar — Lunar New Year, Chuseok, Buddha's Birthday — so a solar rule cannot place them. Election days are statutory holidays fixed by an election schedule. Temporary holidays are declared ad hoc: 2023-10-02 became one a few weeks before it happened. And the statutory list itself is amended: Constitution Day was a holiday until 2007, was removed, and came back in 2026; Labor Day became one in the same amendment.
So this is a table, not an algorithm. The question is whose table.
The source
| Publisher | Korea Astronomy and Space Science Institute, via data.go.kr (dataset 15012690) |
|---|---|
| Licence | 이용허락범위 제한 없음 — no restriction |
| Coverage | 2004–2028. Outside that the API returns 404, not a guess. |
| English names | Added here. The source publishes Korean only. |
What we had to fix
The source is authoritative and still not directly usable.
| Spelling drifted | 신정 became 1월1일 and 석가탄신일 became 부처님오신날 in 2018; 2013 carries 어린이 날 with a stray space. Grouping by name splits one holiday into several. 38 raw spellings normalise to one set. |
| Substitutes were anonymous | Before 2024 a substitute holiday is just 대체공휴일 — it does not say what it stands in for. We derive it, and verify the derivation against the 14 the source does annotate. |
| Rows were missing | Five election days (2004, 2006, 2007, 2008, 2010) and the 2015-08-14 temporary holiday are absent. Added, and every row carries which source it came from. |
Checked against an independent implementation
A holiday table cannot be validated by a schema — the question is not whether the shape is
right but whether the dates are. There is no answer key, so the table is compared date-for-date
against python-holidays, which derives the same calendar by a completely different
method. Across 25 years and 431 dates,
they agree exactly — but only after the six missing rows above were added.
The comparison runs on every build.
Agreement is not proof. Both could be wrong together, and this project's own hand-written table was wrong twice in the same week. What the check catches is one side drifting.
What the free alternatives get wrong
There are free Korean holiday sources, and it is worth being specific about them rather than claiming to be better in the abstract. Taking 2023 as the test year:
date.nager.at | Lists Constitution Day, which was not a holiday in 2023. Omits 2023-10-02, which was. Drops Lunar New Year's actual day and keeps only the substitute. Free and no key, and wrong on roughly two rows a year. |
python-holidays | Correct for 2023, and correct for every year we compared. It is a library, not an API, it publishes no substitute-target for older years, and its English names are phrases like The day preceding Korean New Year. It is used here as a check, not a competitor. |
Staleness
What can go stale here is not a date being wrong; it is a new temporary holiday being declared while the table has not caught up. Those arrive by decision, not by rule, so there is nothing to compute ahead of time. The table is re-fetched from the source and diffed against what is published, which puts the lag at the source's rather than ours.
Something missing or wrong? Say so — it is read by the person who builds this.