Open conventions
How we calculate
A chart depends on its rules. Here are ours, together with the cases used to check them.
The year, month and local clock
The year changes at Lichun (Start of Spring). The month changes at each of the twelve jie solar terms. We use the city's IANA time zone, including historical daylight saving time. A skipped local hour is rejected; a repeated hour requires your choice.
Civil time is the default. Optional true solar time applies longitude and the equation of time to the day and hour boundaries. It does not move the actual UTC instant used for solar-term comparisons.
Two ways to treat Zi hour
Zi hour runs from 23:00 to 00:59. In sect 1, the day pillar changes at 23:00. In sect 2 (our default), the late Zi hour at 23:00–23:59 keeps the current civil day's day pillar, while the hour stem follows the next day. The two conventions can give different results.
Without a birth time, the hour pillar stays unknown. We show three pillars and flag uncertainty near boundaries. No noon birth time is assumed.
Public chart comparisons
Each row records the input, engine result, independent reference and explanation. “Not verified” is not a match.
| Input | Our result | Reference source | Match? | Notes |
|---|---|---|---|---|
| 1988-02-03 12:00 · us-new-york | 丁卯 / 癸丑 / 戊子 / 戊午 | github.comChecked 2026-10-21 | Yes | Local day before the 1988 Beginning of Spring. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1988-02-05 12:00 · us-new-york | 戊辰 / 甲寅 / 庚寅 / 壬午 | github.comChecked 2026-10-21 | Yes | Local day after the 1988 Beginning of Spring. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 2005-12-23 08:37 · us-los-angeles | 乙酉 / 戊子 / 辛巳 / 壬辰 | github.comChecked 2026-10-21 | Yes | 6tail published EightChar test1, adapted to Los Angeles. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1988-02-15 22:30 · us-chicago | 戊辰 / 甲寅 / 庚子 / 丁亥 | github.comChecked 2026-10-21 | Yes | 6tail published EightChar test3, adapted to Chicago. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1988-02-15 23:30 · us-new-york · hourSect=2 | 戊辰 / 甲寅 / 庚子 / 戊子 | github.comChecked 2026-10-21 | Yes | 6tail published EightChar test2: late Zi retains the civil day pillar. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1988-02-15 23:30 · us-new-york · hourSect=1 | 戊辰 / 甲寅 / 辛丑 / 戊子 | github.comChecked 2026-10-21 | Yes | 6tail published EightChar test2a: late Zi advances the day pillar. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1988-02-16 00:30 · us-new-york · hourSect=2 | 戊辰 / 甲寅 / 辛丑 / 戊子 | github.comChecked 2026-10-21 | Yes | Early Zi uses the new civil day under both sects. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1988-02-16 00:30 · us-new-york · hourSect=1 | 戊辰 / 甲寅 / 辛丑 / 戊子 | github.comChecked 2026-10-21 | Yes | Early Zi uses the new civil day under both sects. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 2007-03-11 02:30 · us-new-york | No chart: dst_nonexistent | www.nist.govChecked 2026-10-21 | Yes | NIST: the 2007 spring change skips 02:00 through 02:59. NIST confirms the 2007 transition date. The local clock jumps from 01:59:59 EST to 03:00:00 EDT. The API error name is the v11 product mapping of a nonexistent instant. |
| 2007-11-04 01:30 · us-new-york · dstAmbiguity=ask | No chart: dst_ambiguous | www.nist.govChecked 2026-10-21 | Yes | NIST: the 2007 autumn change repeats 01:00 through 01:59. NIST confirms 02:00 daylight time rolls back to 01:00 standard time. 01:30 EDT is 05:30 UTC and 01:30 EST is 06:30 UTC; v11 ask must expose both instead of choosing. |
| 2007-11-04 01:30 · us-new-york · dstAmbiguity=earlier | 丁亥 / 庚戌 / 壬寅 / 辛丑 | github.comChecked 2026-10-21 | Yes | Earlier occurrence is EDT (UTC−04:00). Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 2007-11-04 01:30 · us-new-york · dstAmbiguity=later | 丁亥 / 庚戌 / 壬寅 / 辛丑 | github.comChecked 2026-10-21 | Yes | Later occurrence is EST (UTC−05:00). Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 2007-03-11 02:30 · us-phoenix | 丁亥 / 癸卯 / 甲辰 / 乙丑 | github.comChecked 2026-10-21 | Yes | Phoenix observes MST (UTC−07:00) throughout the year; this time exists. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1990-05-03 time unknown · us-new-york | 庚午 / 庚辰 / 戊辰 / Unknown hour | github.comChecked 2026-10-21 | Yes | v11 three pillars: civil date day pillar, no fabricated birth instant. Run reference year/month at the civil day's local noon converted to UTC+8 only to classify the date; run reference day at civil noon under sect 2; remove hour as explicitly required by v11. Noon is not recorded as a birth instant. |
| 1990-05-03 time unknown · us-new-york · hourSect=1 · useTrueSolarTime=true | 庚午 / 庚辰 / 戊辰 / Unknown hour | github.comChecked 2026-10-21 | Yes | v11 ignores hourSect and true solar time when the birth hour is unknown. Run reference year/month at the civil day's local noon converted to UTC+8 only to classify the date; run reference day at civil noon under sect 2; remove hour as explicitly required by v11. Noon is not recorded as a birth instant. |
| 1988-02-04 time unknown · us-new-york | No chart: hour_required | github.comChecked 2026-10-21 | Yes | Reference Beginning of Spring: 1988-02-04 14:42:49 UTC, 09:42:49 EST. v11 requires a birth hour. Independently run the reference implementation to establish that the named Jie occurs within this local civil day. Error hour_required is mandated by contract v11; lunar-javascript itself has no missing-hour/error API. |
| 2005-03-05 time unknown · us-new-york | No chart: hour_required | github.comChecked 2026-10-21 | Yes | Reference Awakening of Insects: 2005-03-05 11:45:10 UTC, 06:45:10 EST. v11 requires a birth hour. Independently run the reference implementation to establish that the named Jie occurs within this local civil day. Error hour_required is mandated by contract v11; lunar-javascript itself has no missing-hour/error API. |
| 1970-01-01 12:00 · us-new-york | 己酉 / 丙子 / 辛巳 / 甲午 | github.comChecked 2026-10-21 | Yes | Inclusive minimum supported year; sexagenary year still 1969 before Beginning of Spring. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 2008-12-31 23:30 · us-los-angeles · hourSect=2 | 戊子 / 甲子 / 乙巳 / 戊子 | github.comChecked 2026-10-21 | Yes | Inclusive maximum supported civil year; late Zi hour uses the next day stem. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |
| 1999-06-07 09:11 · us-denver | 己卯 / 庚午 / 庚寅 / 辛巳 | github.comChecked 2026-10-21 | Yes | 6tail published EightChar test12, adapted to Denver. Run reference year/month at the real instant expressed as UTC+8; run reference day/hour at the original local civil date and time with the selected sect. This adapts the reference library's UTC+8 solar terms to a US city without shifting the local day pillar. |