BaZi: the four pillars

BaZi (八字, “eight characters”) is the four pillars of a birth: year, month, day and hour, each with its own heavenly stem and earthly branch. The pillars are the surface. The classical reading is built from what sits underneath them.

Endpoints

The pillars

Endpoint	Credits	Returns
POST /v1/bazi/four-pillars	10	All four pillars
POST /v1/bazi/day-master	10	The day master and its archetype
POST /v1/bazi/ten-gods	10	The ten gods relative to the day master
POST /v1/bazi/luck-pillars	10	大運 luck pillars with the real 起運 start age

Chart analysis

Endpoint	Credits	Returns
POST /v1/bazi/chart	20	Everything below in one call
POST /v1/bazi/hidden-stems	10	藏干: what each branch shelters, with role and weight
POST /v1/bazi/element-balance	10	Element balance over all eight characters, three ways
POST /v1/bazi/na-yin	10	納音, the sound-element of each pillar
POST /v1/bazi/life-stages	10	十二長生, the twelve stages
POST /v1/bazi/symbolic-stars	10	神煞: peach blossom, travelling horse, canopy, nobleman, blade, void
POST /v1/bazi/interactions	10	刑冲合害: combinations, clashes, harms, punishments
POST /v1/bazi/strength	10	Day-master strength in the 扶抑 framework

Hidden stems 藏干

Every branch shelters one to three stems, and this is where most of a chart’s elements live. A chart with no visible Water can still be soaked in it.

Roles: 本氣 principal, 中氣 middle, 餘氣 residual. On the four storage branches (丑辰未戌) the middle role belongs to the element the branch stores, not to the second entry in the list: 丑 stores metal, 辰 water, 未 wood, 戌 fire. The list order follows the 人元司令 day counts, so on those four the second entry is the leftover of the previous season.

Element balance

Three counts rather than one, because practitioners genuinely use different ones and a single number would be a school choice wearing the clothes of a fact.

Field	What it counts
balance.visible	Four stems plus each branch’s principal hidden stem: the classic eight
balance.withHiddenStems	Every sheltered stem, counted whole
balance.weighted	Each branch split among what it shelters, so the total stays at eight

Deprecated fields

The top-level elementCounts, dominantElement and missingElements count the year and month only, four characters of eight, and never open the branches. They keep answering exactly as before until 2027-09-08 and carry RFC 8594 Deprecation and Sunset headers. Everything new lives under balance.

Where the schools part

Five places, and each ships both readings rather than one.

What	One reading	The other
Yin-stem direction through the twelve stages	陽順陰逆 (stageSchool=classical)	陰陽同生同死 (stageSchool=unified)
The yin blade 陰刃	by 帝旺	by 祿前一位
The 庚 nobleman 天乙貴人	三命通會: 丑 and 未	淵海子平: 午 and 寅
The element of the 午未 harmony	Earth	the sun-and-moon pair, no element
Strength thresholds	0.55 / 0.45, our convention	no canonical rule exists

Day-master strength

One framework, and it is named: 扶抑, support against suppression. Everything that produces or shares the day master supports it; everything else drains it.

Two limits are stated in the response itself. The month branch is counted like the other three, where the tradition weighs the month above all, and the 0.55 / 0.45 cut points are our convention rather than canon. So the three classical criteria (得令 season, 得地 root, 得勢 allies) are returned unweighted beside the ratio: a reader who weighs the month reaches their own verdict from the same inputs.

調候, 通關, 病藥 and 專旺 are other frameworks, are not applied here, and can reach the opposite verdict.

True solar time

curl -X POST https://api.astroway.info/v1/bazi/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1995-06-15",
    "time": "09:20:00",
    "timezoneOffset": 8,
    "longitude": 75.9,
    "trueSolarTime": true
  }'

The correction reaches the day and the hour, and stops there: the year and month turn on instants of the world clock. Details and the cost of getting it wrong on the conventions page.

Example

Whole chart

curl -X POST https://api.astroway.info/v1/bazi/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "date": "1990-05-15", "time": "14:30:00", "timezoneOffset": 8, "language": "en" }'

Strength only

curl -X POST https://api.astroway.info/v1/bazi/strength \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "date": "1990-05-15", "time": "14:30:00", "timezoneOffset": 8 }'