Many Koreans celebrate their birthday on the lunar calendar, so the solar (Gregorian) date moves every year — which is exactly why a hard-coded reminder fires on the wrong day. This API turns a birth date into its lunar birthday once, then resolves that lunar birthday to the correct solar date for any year you ask about.
A lunar birthday reminder is a two-step conversion. First, convert the person's solar birth date to its Korean lunar date with /v1/lunar/solar-to-lunar — that lunar month/day (plus the leap-month flag) is their lunar birthday and never changes. Then, for whatever year you want a reminder in, convert that lunar month/day back to a solar date with /v1/lunar/lunar-to-solar. Both steps are leap-month (윤달) aware, so the round trip is lossless and the reminder lands on the right day.
| GET | /v1/lunar/solar-to-lunar?date=1991-05-15 |
Step 1 — solar birth date to the Korean lunar birthday (month/day + leap-month flag). |
| GET | /v1/lunar/lunar-to-solar?date=2026-04-02&leap=false |
Step 2 — that lunar birthday in a target year, as a solar date to schedule the reminder. |
# Step 1: born solar 1991-05-15 -> lunar birthday is the 2nd day of the 4th lunar month
curl "https://korea-calendar-api.kunstudio.workers.dev/v1/lunar/solar-to-lunar?date=1991-05-15"
# Step 2: when does that lunar birthday fall in 2026?
curl "https://korea-calendar-api.kunstudio.workers.dev/v1/lunar/lunar-to-solar?date=2026-04-02&leap=false"// Step 1 response
{
"solar": "1991-05-15",
"lunar": { "year": 1991, "month": 4, "day": 2, "leap_month": false },
"gapja": { "year": "신미년", "month": "계사월", "day": "을유일" }
}
// Step 2 response — schedule the 2026 reminder for this solar date
{
"lunar": { "year": 2026, "month": 4, "day": 2, "leap_month": false },
"solar": "2026-05-18"
}No API key is needed on the origin to try this — it is rate-limited for fair evaluation. See the OpenAPI spec for the full schema.
lunar.month, lunar.day and leap_month from Step 1 and reuse them every year in Step 2 — only the target year changes. The lunar birthday itself is fixed.leap=true in Step 2. Note that a given lunar month is not a leap month every year, so a leap-month birthday may need a fallback rule (commonly the same month in its regular form) — that policy is your app's to decide.Building a Korean fortune (사주/saju) app? Pair this with the KunStudio Saju API for a full four-pillars reading over REST.