# 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

<Tabs>
  <TabItem label="One day">
    ```bash frame="terminal"
    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" }'
    ```
  </TabItem>
  <TabItem label="Pick a date">
    ```bash frame="terminal"
    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" }'
    ```
  </TabItem>
</Tabs>

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

<Aside type="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`.
</Aside>

<Aside type="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.
</Aside>

## 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.