# Zi Wei Dou Shu: star placement

**紫微斗數** builds a chart not from planets but from twelve palaces and well over a hundred stars, placed by rule from the lunar date and the double-hour of birth. `POST /v1/ziwei/chart` computes all of it.

## Endpoints

| Endpoint | Credits | What it returns |
|---|---:|---|
| `POST /v1/ziwei/chart` | 20 | The whole chart: palaces, stars, stages, limits, 四化. Needs `time` and `gender` |
| `POST /v1/ziwei/four-transformations` | 10 | 四化 by year stem, across four schools |
| `POST /v1/ziwei/twelve-palaces` | 5 | Reference glossary of the twelve palaces |
| `POST /v1/ziwei/main-stars` | 5 | Reference glossary of the fourteen main stars |
| `POST /v1/ziwei/palace-*` | 5 | One palace, nine paths |

The reference routes carry a `computed: false` field and cost half the standard rate. They return the same table for any birth date, which is a perfectly good thing to sell as long as it is labelled.

<Aside type="caution" title="`/ziwei/full-chart` is deprecated">
It returns the same palace glossary to everybody while its name promises a chart. It answers unchanged until **2027-11-26**, with `Deprecation`, `Sunset` and a `Link` to the successor. Move to `/v1/ziwei/chart`: it needs `gender` in addition to the date and time.
</Aside>

## Example

```bash
curl -X POST "https://api.astroway.info/v1/ziwei/chart?lang=en" \
  -H "X-Api-Key: $ASTROWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2000-08-16","time":"04:00:00","gender":"male","age":25}'
```

```json
{
  "fiveElementClass": { "key": "wood3", "chinese": "木三局", "name": "Wood 3", "value": 3 },
  "soulPalace": { "index": 4, "branch": "Wu" },
  "bodyPalace": { "index": 8, "branch": "Xu" },
  "ziwei": { "index": 4, "branch": "Wu" },
  "annualLimit": { "age": 25, "index": 8, "branch": "Xu" },
  "palaces": [
    {
      "branch": "Wu",
      "pillar": "Ren-Wu",
      "palace": "destiny",
      "isSoul": true,
      "majorStars": [{ "chinese": "紫微", "name": "Purple Star", "pinyin": "Zi Wei", "kind": "major" }],
      "lifeStage": { "chinese": "死", "name": "Death", "localised": "Death" },
      "boshi": "伏兵",
      "decade": { "index": 0, "fromAge": 3, "toAge": 12 }
    }
  ]
}
```

The `palaces` array carries all twelve in that same shape, from 寅 round to 丑.

## What is computed

| Step | Rule |
|---|---|
| 命宮 and 身宮 | From the month palace, back by the double-hour for the soul, forward for the body |
| Palace stems | 五虎遁 from the year stem |
| 五行局 | From the soul palace pillar; agrees with the na yin reading on all sixty pairs |
| 紫微 | The day divided by the class number with a borrow: an even borrow steps forward, an odd one back |
| 紫微系 (6) | Offsets of −1, −3, −4, −5, −8 from 紫微 |
| 天府系 (8) | 天府 mirrors 紫微 across the 寅-申 axis, then +1..+6 and **+10** for 破軍 |
| Six lucky, six malefic | From the month, the double-hour and the year stem, each with its own rule |
| Thirty-one minor stars | From the year branch, the year stem, the month, the day and the hour |
| 長生十二神 | From the five-element class, forward for a yang man or yin woman, back otherwise |
| 博士十二神 | From 祿存, same direction |
| 將前 and 歲前 十二神 | From the year-branch trine and from the branch itself, both always forward |
| 大限 | From 命宮, opening at the class number, ten years per palace |
| 小限 | Reads sex and **not** polarity, unlike the decades |
| 四化 | By year stem, marked on the stars themselves |

## Four school switches

They live in the request body rather than in our code, because each one moves the whole chart for the births it touches.

| Parameter | Default | Alternative |
|---|---|---|
| `yearDivide` | `lunar`: the year opens on day one of the first lunar month | `lichun`: the BaZi boundary |
| `fixLeap` | `true`: a leap month is split at day 15 | `false`: the whole leap month counts as the one it follows |
| `dayDivide` | `forward`: 23:00 belongs to the next day | `current`: the date stays and the hour is marked 晚子時 |
| `tianmaSchool` | `year`: 天馬 from the year branch (中州派) | `month`: 天馬 from the lunar month |
| `school` | `zhongzhou`: 四化 per the 王亭之 corpus | `quanji`, `quanshu`, `beipai` |

<Aside type="caution" title="The birth time is required">
The soul palace is placed from the double-hour, and the five-element class and every star follow from the soul palace. A chart without the hour would not be a partial answer but twelve palaces of confident nonsense, so a request without `time` is refused with a 400. This differs from BaZi, where a missing hour simply leaves out the hour pillar.
</Aside>

<Aside type="note" title="The year does not start at Lichun here">
That is not a school choice. Zi Wei is a purely lunar system and does not switch to the solar terms the way BaZi does. `yearDivide=lichun` exists only for reconciling against a calculator that imported the BaZi boundary.
</Aside>

## How this was verified

Pinned to three published charts rather than to one library, deliberately. Nearly the whole open-source Zi Wei ecosystem descends from a single project: two ports, plus at least one project advertising a different lineage that calls it internally and parses the output. So agreeing with several projects is agreeing with one.

- Two charts reproduce exactly: all fourteen main stars, the five-element class, the soul and body palaces.
- The twelve stages are checked on a third fixture from the same source, where the expected twelve are published, rather than on those two charts. The decade openings are asserted against the five-element class number, which is the rule they come from rather than an outside publication.
- A further chart comes from a Chinese teaching text with no connection to that ecosystem, and pins the star offsets and the palace order on its own.
- The 安紫微星 mnemonic 「六五四三二／酉午亥辰丑」 and the published 火六局 run for days 1 to 15 are asserted directly: those are constants of the tradition, not somebody's implementation.

<Aside type="tip" title="When your calculator disagrees">
Check the four switches before the arithmetic: the year boundary, the leap month, the 23:00 rollover and the 四化 table. That is almost always where the difference is.
</Aside>

## One common retelling that is wrong

火星 and 鈴星 are placed **forward from the year-branch trine and take no account of sex** in every transmission consulted. The 陽男陰女順 / 陰男陽女逆 rule sometimes attached to them belongs to the twelve life stages and to the decade limits. Both topics sit on the same page in the most-copied source, which is the likely origin of the confusion.

## Languages

The palace names and the twelve life stages are translated into 21 languages: add `?lang=` and each palace gains `palaceLocalised` and each stage a `localised` field. Star names stay as characters with an English gloss beside them, because they have no settled names.