DEV Community

The hard part of a BaZi calculator isn't the astrology - it's the time zones

When I started building a BaZi (Four Pillars) calculator, I assumed the hard part would be the astrology - the rules, the terminology, the interpretation. The rules turned out to be a lookup table.

The hard part was that every birth record in the world gives you a time that isn't the time the calculation actually needs. Here are the five traps, roughly in the order they bit me.

1. IANA time zones are city-based. Birthplaces are not.

Asia/Shanghai has been a flat +08:00 since 1901. That's true for the zone. It is not true for a birthplace.

China spans about 60 degrees of longitude and uses a single zone. Standard time is defined at 120°E. Chengdu sits at 104.07°E: (104.07 - 120) × 4 minutes per degree ≈ -64 minutes. Local mean time in Chengdu runs roughly 64 minutes behind the clock on the wall.

Use the zone offset naively and the hour pillar can land in the wrong two-hour branch. The general rule is one degree of longitude equals four minutes of time, and IANA will never tell you that.

2. Mean solar time is not solar time

Fixing longitude gets you local mean time. The sun does not run on mean time. Earth's orbit is elliptical and its axis is tilted, so apparent solar time drifts from mean solar time across the year by up to about ±16 minutes - the equation of time.

If a day-branch boundary falls a few minutes from midnight, that drift is enough to flip the day.

true solar time = civil time + (longitude - standard meridian) × 4 min + equation of time + historical DST offset

3. Historical offsets are not what you think

Modern zone data is orderly. Historical data is not:

  • China observed DST from 1986 to 1991.
  • Wartime and occupation periods shifted offsets by an hour or more.
  • Some regions changed their standard meridian outright.

For a 1988 birth in Shanghai, the IANA row is a starting point, not an answer. You have to ask what offset was actually in force that day, and be honest when the answer is "we are not certain".

4. Correcting the time can move the date

This is the subtle one. Apply a correction near midnight and the resulting solar time belongs to the previous or next day. That changes the day pillar, which changes everything downstream.

An implementation that treats the correction as "adjust the clock" instead of "produce a new instant plus a date-shift flag" will silently produce wrong charts. The output has to say this rolled over, not just hand back a formatted string.

5. Calendar months are not solar months

Year and month pillars don't start on January 1 or on the first of any month. The year begins at 立春 (Lichun), and month boundaries are the 节 solar terms - each of which happens at a specific instant, not on a date.

A birth on the calendar day of a term boundary can belong to either month depending on the hour. Solar terms are astronomical events. You need ephemeris-backed calculation, not a hardcoded date table.

What this means for the design

The mistake I made first, and the one I'd warn anyone about: collapsing all corrections into a single offset. Once you return one number, nobody downstream can tell whether a strange result came from longitude, from the equation of time, or from a DST rule. So return the components:

{
  "civilTime": "1990-05-20T14:30:00+08:00",
  "utc": "1990-05-20T06:30:00Z",
  "trueSolarTime": "1990-05-20T13:29:46",
  "longitudeCorrectionMinutes": -63.73,
  "equationOfTimeMinutes": 3.5,
  "daylightSavingMinutes": 0,
  "dateShift": 0,
  "warnings": [],
  "engineVersion": "..."
}

Three properties I'd keep in any version of this:

  • Separate the components. A single offsetMinutes is a debugging dead end.
  • Flag the boundaries. If the corrected time lands within a few minutes of midnight, or within a few hours of a solar term, say so. A confident wrong answer is worse than a hedged right one.
  • Version the engine. The rules have schools and conventions - treating 23:00 as the start of the next day instead of midnight is one such choice. When results change, callers need to know which engine produced them.

None of this is specific to BaZi. It applies to anything that starts from "a date, a time, and a place" - genealogy, astronomy, anything touching pre-1970 records in a country that changed its clocks.

Where I landed

I ended up splitting the time normalization out as standalone, read-only MCP servers, because re-implementing it per project was getting silly:

  • calculate_true_solar_time - civil time, IANA zone, and longitude in; UTC, true solar time, and each correction component out
  • calculate_four_pillars - the same inputs, plus solar-term boundaries, out as year/month/day/hour pillars

Both are MIT, with no geocoding, no stored birth data, and no LLM anywhere in the calculation path:

Disclosure, since this is my own work: I also run the calculator these came from, and you can see the output on a real chart at https://bazi-calculator.co/

If you've hit this class of bug in another domain, I'd like to hear how you handled it - especially the "this local time never existed" case around DST transitions, which is still the part I trust least.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.