The conventions we use
| Question | Our default | Can you change it? |
|---|---|---|
| When does the year pillar change? | At the exact moment of 立春 (Start of Spring) | No |
| When does the month pillar change? | At the exact moment of each of the 12 jie solar terms | No |
| Which time decides year and month? | The absolute instant of birth (solar terms happen at the same instant worldwide) | No |
| Which time decides day and hour? | Local true solar time (longitude + equation of time) | Yes — switch to clock time |
| Births 23:00–24:00 | Hour pillar = 子 hour of the next day’s stem; day pillar stays on the same date | Yes — switch the day pillar to the next day |
| Historical time zones / daylight saving | IANA time-zone database built into your browser | Yes — enter a time zone manually |
| Times repeated when clocks go back | First occurrence | Yes |
| Luck pillar direction | Yang-year male / yin-year female forward; otherwise backward | Via the gender setting |
| Luck pillar start age | Exact minutes to the relevant jie term, 3 days = 1 year; ages in completed Western years | No |
| Hidden stems | Standard table (main stem first), as in our guide | No |
| Five-element figures | Raw counts, not a strength score | — |
Software and data
- Calendar engine: lunar-javascript by 6tail, MIT licence. It provides the solar-term moments, the sixty-pair cycle, Na Yin and the luck-pillar arithmetic. We vendor a copy so the site works offline and cannot change under us.
- Our own code: time-zone conversion (including detection of non-existent and repeated local times), the longitude correction, the equation of time (NOAA/Spencer formula), the choice of which instant drives which pillar, hidden stems, ten gods, element counts and boundary warnings.
- Places: GeoNames “cities15000” list (about 34,000 places with population over 15,000), with latitude, longitude and IANA time zone. Licence CC BY 4.0, © GeoNames.
- Classical texts: quotations are copied from public-domain transcriptions on Chinese Wikisource and checked automatically: our build refuses to publish a quote that does not appear verbatim in the source text we downloaded.
Test results
We run an automated test suite every time the code changes. Current results:
4862/4869 checks passed (99.86%)
- Solar-term dates vs the Hong Kong Observatory, 1901–2100: 4794/4800 dates match. All mismatches are terms that fall within about 12 minutes of midnight, where the two sources put the term on adjacent dates: 1912-11-23 小雪, 1913-09-24 秋分, 1917-12-07 大雪, 1927-09-08 白露, 1928-06-21 夏至, 1979-01-21 大寒. Of these, only 大雪 1917 and 白露 1927 are jie terms that change a month pillar, and only for births within minutes of the term.
- 2025 principal solar terms to the minute vs the Hong Kong Observatory: 12/12 within one minute.
- Day pillar vs an independent formula (Julian day number, 1800–2099, sampled every 37 days): all match.
- Published charts of historical figures: 34/35 match all four pillars. The one mismatch is Albert Einstein: the source lists the hour pillar 庚寅, but the time it gives (about 11:30) is in the 午 hour, and a 丙 day can only have 甲午 there — the source’s hour pillar is internally inconsistent. The source for most of these charts is a Chinese compilation of published charts; we record each source in our test file.
- Behaviour checks (daylight saving in China 1990, US clock changes, equation-of-time extremes, true solar time in Urumqi and Madrid, the 立春 boundary in Hong Kong and London, both late-Zi conventions, luck-pillar direction, ten-god table): 22/22 pass.
Known limitations
- Places smaller than 15,000 people are not in the list; choose the nearest city or enter coordinates.
- Historical time-zone data before about 1970 is the best available but not perfect, especially for local practice in wartime.
- Dates before 1800 and after 2100 are outside our tested range.
- We do not yet calculate the twelve life stages, interactions, or a useful god; the guides explain how they work.
Found an error?
If you have a chart from a reliable source that our calculator gets wrong, we want to know. Contact details are on the About page.