Tong Shu (date selection)

Tong Shu (通書) is the Chinese almanac people traditionally pick a date from. Two of its layers are exactly computable, and those are the two implemented here: the twelve day officers (建除十二神) and the twenty-eight mansions (二十八宿).

Endpoints

Endpoint	Credits	What it returns
POST /v1/chinese/tong-shu	10	One day: day pillar, officer, mansion, the animal it clashes
POST /v1/chinese/tong-shu/select	20	The days in a range the register endorses for one activity

The twelve day officers

One rule. The day whose earthly branch equals the month’s branch is 建 Establish, and the twelve run in order from there. The month here is bounded by the exact solar term, not by the first of the calendar month, so an officer can change mid-month.

#	中文	Name	What the day is about
1	建	Establish	Beginning, not completing
2	除	Remove	Clearing out, getting rid of
3	滿	Full	Fullness, signing, opening
4	平	Balance	Level, ordinary, safe
5	定	Stable	What is meant to last
6	執	Control	Taken in hand
7	破	Destruction	The day that clashes the month
8	危	Danger	Height and exposure
9	成	Success	The most auspicious of the twelve
10	收	Collect	Gathering in, receiving
11	開	Open	Opening, guests, new roles
12	閉	Close	Sealing; the qi at its lowest

The twenty-eight mansions

The mansion advances one per day on an unbroken 28-day cycle, and that cycle is locked to the week: 角 is always Thursday, because 28 is exactly four weeks. The property is not decorative, it is the check: a wrong anchor would either shift the sequence against the published almanac or break the weekday.

Example

One day

curl -X POST https://api.astroway.info/v1/chinese/tong-shu \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-09-12" }'

Pick a date

curl -X POST https://api.astroway.info/v1/chinese/tong-shu/select \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-09-01", "to": "2026-12-31",
        "activity": "marriage", "avoidClashWith": "Rat" }'

Activities: marriage, opening, moving, travel, contract, construction, demolition, medical, funeral, education.

Note

Three verdicts, and neutral does not mean “fine either way”. suitable and unsuitable are what the register states outright. neutral means the tradition is silent about that activity on that officer. Silent days are therefore excluded by default, and you can ask for them with includeNeutral.

Caution

The range is capped at 366 days, and a longer one is refused rather than truncated. A silently shortened answer would read as “no good days after March” when the truth is that nothing was looked at. Every response carries scanned, matched and dropped broken down, so the numbers add up.

What was verified

• The officers against a published worked example: December 2020 in the Rat month, where 11 December is the first Establish day and 8, 9 and 10 December are Collect, Open and Close. All four match.
• The mansions against a Japanese almanac’s day-by-day sequence for August 2026: twenty consecutive days, from 女 on the 1st to 角 on the 20th. Plus the weekday invariant, checked across a century of dates.
• The day pillar is now pinned by the three published dates (1949-10-01 甲子, 2000-01-01 戊午, 2024-02-10 甲辰) that its own comment had named for months without anything asserting them.

Selection runs on the officers, not on the mansions. The mansion is reported for every day but does not filter: its per-activity register varies between almanacs, and we do not invent one. The 神煞 spirit tables are absent for the same reason: dozens of overlapping series with no agreement between sources.