November 5, 2026
·Jackson
The Chinese Calendar, Computed From the Sky: Lunar Dates, Solar Terms and the Almanac
Convert any date between the Gregorian and Chinese lunar calendars, with leap months, the four pillars, solar terms at their exact instants and the Tong Shu basics. Computed from new moons and the Sun, and checked against the Hong Kong Observatory.
Most Chinese calendar tools are lookup tables. This one is computed. The months start at the real new moon and the solar terms fall at the real instant the Sun reaches each 15 degrees of longitude, both from the NASA JPL DE440 ephemeris. The result is the calendar the modern rules give, for any date from Chinese New Year 1645 to the end of 2648.
Two routes
POST /chinese/calendar/convert takes a date and returns what that day is in the Chinese calendar, or takes a lunar date and returns the Gregorian one. POST /chinese/calendar/almanac returns one Gregorian month, day by day.
Each day carries:
- the lunar year, month and day, whether the month is a leap month, and the zodiac animal;
- the year, month, day and hour pillars (the stem and branch of each);
- the solar term in force, and the next one with its exact instant;
- the Tong Shu basics: the day officer, the 28 lodges, the clash and the sha direction.
Names come in simplified and traditional Chinese and in pinyin.
An example: Chinese New Year 2027
Asking for 2027-02-06 in Asia/Shanghai returns:
- lunar year 2027, month 1, day 1 (正月初一), the year of the Goat, with year pillar 丁未;
- Lichun (立春) already in force, at 2027-02-04 09:46:18 Beijing time;
- day pillar 丙辰, day officer 满 (Man), the lodge 氐 (Di), a clash with the Dog, and sha to the south;
- the next solar term, Yushui (雨水), at 2027-02-19 05:33:28.
That date also shows the honesty built into the answer. A new moon or solar term falls within about four minutes of midnight in Beijing, so the response sets boundary_warning and gives boundary_margin_seconds (233). A calendar date can be settled by a few minutes, and the answer tells you when it is.
How it was checked
The reference is the Hong Kong Observatory's published tables, 1901 to 2100:
- every Chinese New Year and every leap month agrees;
- 2,467 of 2,473 months agree, and 4,792 of 4,800 solar-term dates agree;
- the differences are new moons or terms within 26 minutes of Beijing midnight, and six of the eight differing term dates fall in 1909 to 1913, where the observatory keeps the almanac as it was then issued.
Two limits worth knowing. Before 1912 this is the calendar the modern rules give, not the almanac the Qing court issued, whose astronomy differs in some months. And far in the future the length of the day is a prediction, so toward 2650 a new moon or term within roughly 10 to 20 minutes of Beijing midnight may belong to the other date. The response says so in its metadata.
The rules, written down
Every choice is named in the response: the month holding the winter solstice is month 11, the first month with no major solar term in a 13 month year is the leap month, the year pillar changes at Lichun, and the Zi hour starts at 23:00 and takes the day's stem. Calendar dates never move with the timezone you send; only the hour pillars follow your clock.
Ask for it in Claude
In Claude, ask "what is the Chinese lunar date for 6 February 2027" and the assistant finds the route and runs it. This works in Claude today; ChatGPT does not reach it yet.