Korean Age Calculator API

There is no single “age” endpoint on purpose — the three Korean age formulas are simple arithmetic, but they hinge on which day it is in Korea, and a server in another timezone can be a day off near midnight. So the pattern is: fetch /v1/today for the current KST date, then compute each age locally from the birth date. 만 나이 (international) = years since birth, minus one if this year's birthday hasn't happened yet. 세는 나이 (traditional) = current year − birth year + 1 (you are 1 at birth and gain a year every January 1). 연 나이 (year age) = current year − birth year. Keeping the formulas in your code lets you pick which system to display while the API guarantees the KST reference date.

Endpoints

Example request & response

# Get today in Korea (KST), then compute the three ages in your own code.
curl "https://korea-calendar-api.kunstudio.workers.dev/v1/today"

{
  "date_kst": "2026-06-15",
  "is_holiday": false,
  "holiday": null
}

// Then in your app (JS), for a birth date of 1998-08-20:
// const today = "2026-06-15";          // from /v1/today (date_kst)
// const [ty, tm, td] = today.split("-").map(Number);
// const [by, bm, bd] = "1998-08-20".split("-").map(Number);
//
// // 만 나이 (international / legal — the standard since June 2023)
// let manAge = ty - by;
// if (tm < bm || (tm === bm && td < bd)) manAge -= 1;   // birthday not reached yet
//
// const semeAge = ty - by + 1;   // 세는 나이 (traditional counting age)
// const yeonAge = ty - by;       // 연 나이 (year age)
//
// manAge  -> 27   // hasn't turned 28 yet in 2026
// semeAge -> 29
// yeonAge -> 28

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.

Good to know

• Use date_kst from /v1/today as the reference date so the age is correct in Korea time — a server in the US or EU can otherwise be a calendar day off, which flips the answer for birthdays right around midnight.
• 만 나이 (international/legal age) has been South Korea's official legal standard since June 2023. Compute it as full years since the birth date, subtracting one if this year's birthday has not occurred yet. This is the value to show by default in legal, signup-eligibility and KYC contexts.
• 세는 나이 (traditional counting age) = current year − birth year + 1 (a newborn is 1, and everyone gains a year on January 1, not on their birthday). 연 나이 (year age) = current year − birth year, used in some statutes (e.g. military, youth-protection screening). Display these only where the cultural/statutory context calls for them.
• Lunar birthdays: if a person celebrates on the lunar calendar, first resolve this year's solar birthday with the Korean Lunar Birthday API, then run the 만 나이 formula against that solar date.
• The arithmetic stays in your code so you control which system to display; the API's job is to give you the correct KST reference date and (optionally) the lunar→solar conversion.

Related

Building a Korean fortune (사주/saju) app? Pair this with the KunStudio Saju API for a full four-pillars reading over REST.