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.

`/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.

Example

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}'

{
  "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

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.

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.

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.

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.

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.