If you have ever tried to build a Korean fortune-telling or astrology app, you already know the dirty secret: the fun part is the interpretation, and the brutal part is the date math. Saju (사주), the Korean "Four Pillars of Destiny," is computed from a person's birth year, month, day, and hour. Sounds like four lookups. It is not.
I built and shipped a small HTTP API to do exactly this part for me, because I got tired of every Western reimplementation quietly returning the wrong pillars. This is a writeup of why the math is hard and how the API works.
Why Korean Saju date math is hard
The Four Pillars are four pairs of characters (Heavenly Stem + Earthly Branch), one pair for the year, month, day, and hour. To compute them correctly you have to handle three things that trip up almost every naive implementation:
The lunisolar calendar. Saju is rooted in a calendar that tracks both the moon and the sun. You cannot just do modular arithmetic on a Gregorian date. Solar to lunar conversion is table-driven and irregular, and getting a single month's leap-month placement wrong cascades into every downstream pillar.
