Chinese metaphysics API

53 endpoints across four families: BaZi (18), the Chinese calendar and zodiac (15), Zi Wei Dou Shu (14) and I Ching (6). The calendar is derived from the ephemeris rather than from date tables, so it works for years 2 through 2899 and does not depend on whether somebody refreshed a reference.

What is included

Family	Endpoints	State
BaZi: pillars and analysis	18	The full classical apparatus
Calendar, zodiac, feng shui, Tong Shu	15	Derived from the ephemeris
Zi Wei Dou Shu	14	Star placement computed, eleven glossaries stay glossaries
I Ching	6	Hexagrams, coin toss, changing lines

How this differs from a free library

The honest answer: if all you need is the four pillars, take lunar-typescript. It is MIT, it runs in your own process, offline, with no rate limit, and you should not pay for that.

The difference starts where the library stops.

Feature	MIT libraries	AstroWay API
Four pillars, 藏干, na yin, 十神	yes	yes
神煞 with both readings where the schools part	no	yes
Branch interactions 刑冲合害	no	yes
Day-master strength in the 扶抑 frame	no	yes
True solar time as a first-class computation	no	yes
Flying stars by sitting and facing, the Kua number	no	yes
Tong Shu date selection filtered by activity	no	yes
Twenty-one languages	no	yes
One convention across PHP, JavaScript and Python at once	no	yes

That last row is what people actually pay for. A team whose site is PHP, whose app is JavaScript and whose crons are Python otherwise keeps three implementations of the year boundary, and sooner or later gets three different answers for one birth date.

Conventions said out loud

Four axes where calculators part company, and none of them is a bug. Most implementations choose silently; we write the choice into the response and keep a conventions page with a run against an external CC0 dataset.

Axis	Our answer
Year boundary	立春 Lichun, the exact instant from the ephemeris
Day rollover	23:00, so the early 子時 belongs to the next day
True solar time	off by default, switched on by a flag
Daylight saving	settled by the timezoneOffset the client sends

Example

curl

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

TypeScript

import { Astroway } from '@astroway/sdk';

const aw = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const r = await aw.client.POST('/bazi/chart', {
  body: { date: '1990-05-15', time: '14:30:00', timezoneOffset: 3 },
});
console.log(r.data?.data?.pillars.map((p) => p.pillar));
// [ 'Geng-Wu', 'Xin-Si', 'Geng-Chen', 'Gui-Wei' ]

Python

import os
from astroway import Astroway

aw = Astroway(api_key=os.environ["ASTROWAY_API_KEY"])

chart = aw.post("/bazi/chart", body={
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 3,
})
print([p["pillar"] for p in chart["pillars"]])
# ['Geng-Wu', 'Xin-Si', 'Geng-Chen', 'Gui-Wei']

Typed methods

The BaZi analysis routes landed after the current SDK release, so there is no typed aw.bazi.chart(...) yet. The examples above use the raw client, which works with any path today. Typed wrappers arrive with the next SDK release.

A working app you can clone

Live demo and the code on GitHub, MIT.

Two calls, POST /v1/bazi/chart at 20 credits and POST /v1/bazi/luck-pillars at 10, return the four pillars with their hidden stems, na yin and twelve-stage phase, the day master with its strength verdict, the element balance, the symbolic stars, the branch interactions and the ten-year Da Yun cycle. The app draws them: year on the right the way a chart is written, day column marked. The backend is one route and no dependencies, because that is the point: a browser cannot reach the API directly, so the key lives on the server.

git clone https://github.com/astroway/starter-bazi
cd starter-bazi && npm install
cp .env.example .env     # your key goes here
npm run dev

Three things worth taking from it. Send a zone name and not an offset: Asia/Shanghai on 1990-05-15 is UTC+9, because China kept summer time from 1986 to 1991. Send a language: the default is Ukrainian, and an English page without one gets its element names in the wrong language. Send gender: Da Yun runs forward or backward depending on it and there is no neutral value.

Languages

Animals, elements, yin and yang, the palaces and the twelve stages are translated into 21 languages. Add ?lang=es and a *Name field appears next to the English token. The English fields never change: localisation adds, it does not replace.

Stems, branches, star names and na yin are deliberately not translated: their international form is pinyin next to the character.

Documentation

Overview What is computed, what is not, and why.

BaZi: the four pillars Eighteen endpoints and five places where the schools part.

Zodiac and calendar Three animals, the lunar date, the twenty-four terms.

Zi Wei Dou Shu Star placement, the twelve palaces and four school switches.

Conventions Four axes and a run against an external dataset.

Questions we get Unknown birth time, true solar time, the state of Zi Wei.

Flying stars Nine palaces, period, sitting and facing.