# Korea Calendar API

> Free Korean calendar API by KunStudio: public holidays, lunar<->solar conversion,
> the gapja (간지 / sexagenary cycle), the 24 solar terms (절기), and Korean Revised
> Romanization. No API key on the origin. KASI-derived data, served from the edge.

Base URL: https://korea-calendar-api.kunstudio.workers.dev
Auth: none on the origin (rate-limited for evaluation)
OpenAPI: https://korea-calendar-api.kunstudio.workers.dev/openapi.yaml

## Endpoints
- GET /v1/holidays?year=2026 — All Korean public holidays for a year (incl. substitute holidays / 대체공휴일).
- GET /v1/holidays/is?date=2026-09-25 — Is this date a Korean public holiday? Returns the holiday and weekday.
- GET /v1/today — Today's Korean date (KST) and whether it is a public holiday.
- GET /v1/romanize?text=안녕하세요 — Revised Romanization (RR) of Korean text (국립국어원 table).
- GET /v1/lunar/solar-to-lunar?date=2026-02-17 — Convert a solar (Gregorian) date to the Korean lunar date + 간지 (gapja) pillars.
- GET /v1/lunar/lunar-to-solar?date=2026-01-01&leap=false — Convert a Korean lunar date to its solar date (leap=true for 윤달).
- GET /v1/gapja?date=2026-02-17 — 간지 (sexagenary cycle) year/month/day pillars for a solar date, in Hangul + Hanja.
- GET /v1/solar-terms?year=2026 — The 24 solar terms (절기) for a year with KST entry times (astronomically computed, any year).
- GET /v1/solar-terms?date=2026-03-20 — Check whether a specific KST date is one of the 24 solar terms.
- GET /v1/health — Liveness check.

## Use cases
- Calendar & booking apps: Show Korean public holidays (including substitute holidays) so scheduling, shipping ETAs and business-day math are correct.
- Fortune / saju (사주) apps: Convert a birth date to lunar + gapja pillars — the core input for Korean four-pillars fortune-telling.
- Seasonal content & e-commerce: Drive promotions and content off the 24 solar terms (절기) entry times.
- Travel & localization: Romanize Korean names, places and text (RR) for English-facing UIs, and detect holidays for trip planning.

## Guides
- https://korea-calendar-api.kunstudio.workers.dev/guides/korean-lunar-calendar-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/gapja-sexagenary-cycle-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korea-24-solar-terms-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korean-public-holidays-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korea-business-days-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korea-long-weekends-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korean-lunar-birthday-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korean-romanization-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/seollal-chuseok-dates-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korean-zodiac-sign-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/hangul-url-slug-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korean-age-calculator-api
- https://korea-calendar-api.kunstudio.workers.dev/guides/korean-holidays-ical-feed-api

## Related
- Saju API (Korean four-pillars / Bazi over REST, same publisher): https://saju-api.pages.dev

## Data & license
Holidays: statutory Korean public holidays (KASI 특일정보 via data.go.kr, KOGL Type 1, commercial use OK with attribution).
Lunar & gapja: vendored KASI-derived table (1391-2050). 24 solar terms: Meeus astronomical computation (any year in range).