Korean Zodiac Sign (띠) API

There is no separate “zodiac” endpoint — you derive the 띠 from the gapja year pillar, because they are the same thing. Call /v1/gapja?date=YYYY-MM-DD with the birth date; the response's gapja.year (e.g. 병오년) ends in an Earthly Branch character (지지) that maps one-to-one to the twelve animals. Read that last branch character and look it up in the table below. Because the year pillar already rolls over at the lunar new year (and not on January 1), a January-born person correctly gets the previous year's animal — no edge-case math on your side.

Endpoints

Example request & response

# Born 1990-06-15 -> year pillar 경오년; the branch 오(午) = Horse
curl "https://korea-calendar-api.kunstudio.workers.dev/v1/gapja?date=1990-06-15"

# Born 2022-01-15, before Seollal (2022-02-01) -> 신축년; the branch 축(丑) = Ox (the 2021 animal, correctly)
curl "https://korea-calendar-api.kunstudio.workers.dev/v1/gapja?date=2022-01-15"

// 1990-06-15 — read the last char of gapja.year: 오 -> Horse
{
  "solar": "1990-06-15",
  "gapja": { "year": "경오년", "month": "임오월", "day": "신해일" },
  "gapja_chinese": { "year": "庚午年", "month": "壬午月", "day": "辛亥日" },
  "lunar": { "year": 1990, "month": 5, "day": 23, "leap_month": false }
}

// 2022-01-15 — before Seollal, so year pillar 신축년; branch 축 -> Ox
{
  "solar": "2022-01-15",
  "gapja": { "year": "신축년", "month": "신축월", "day": "무진일" },
  "lunar": { "year": 2021, "month": 12, "day": 13, "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

• The zodiac animal is the Earthly Branch (지지) of the year pillar — the second syllable of gapja.year (the part before 년). Map it: 자 Rat (쥐), 축 Ox (소), 인 Tiger (호랑이), 묘 Rabbit (토끼), 진 Dragon (용), 사 Snake (뱀), 오 Horse (말), 미 Sheep (양), 신 Monkey (원숭이), 유 Rooster (닭), 술 Dog (개), 해 Pig (돼지).
• In code: take gapja.year, drop the trailing 년, take the last remaining character (the branch), and look it up in a 12-entry map to your animal name/emoji. Prefer the branch over year % 12 — the API already handled the lunar-new-year boundary so January births resolve correctly.
• Boundary convention: this follows the lunar-calendar (Seollal) boundary used in everyday Korean usage. Some formal saju systems roll the year animal at 입춘 (Start of Spring, ~Feb 4) instead — if your app needs that, cross-check the date against the 24 solar terms API for 입춘 and adjust births in the 설날–입춘 window.
• Range: 1391–2050 (vendored KASI-derived table; self-contained, no third-party call at runtime).

Related

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