Gapja (Sexagenary Cycle) API

Building a saju / fortune app means turning a birth date into its four pillars. The first step is the gapja: the stem-branch pair for the year, month and day. Getting this right requires correct lunar conversion and the traditional pillar conventions — this API handles both and returns the result in Hangul and Hanja.

Endpoints

Example request & response

curl "https://korea-calendar-api.kunstudio.workers.dev/v1/gapja?date=2026-02-17"

{
  "solar": "2026-02-17",
  "gapja": { "year": "병오년", "month": "경인월", "day": "임술일" },
  "gapja_chinese": { "year": "丙午年", "month": "庚寅月", "day": "壬戌日" },
  "lunar": { "year": 2026, "month": 1, "day": 1, "leap_month": false }
}

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

• Output in both Hangul (간지) and Hanja (干支) for every pillar.
• Range: 1391–2050 (KASI-derived table).
• Convention note: some saju systems change the year pillar at 입춘 (Start of Spring) rather than at the lunar new year. This endpoint follows the lunar-calendar convention; pair it with the 24 solar terms API if your app needs the 입춘 boundary.

Related

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