# 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](/en/chinese/conventions/) 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

<Tabs>
<TabItem label="curl">
```bash
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}'
```
</TabItem>
<TabItem label="TypeScript">
```ts

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' ]
```
</TabItem>
<TabItem label="Python">
```python
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']
```
</TabItem>
</Tabs>

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

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

<CardGrid>
  <LinkCard title="Overview" href="/en/chinese/" description="What is computed, what is not, and why." />
  <LinkCard title="BaZi: the four pillars" href="/en/chinese/bazi/" description="Eighteen endpoints and five places where the schools part." />
  <LinkCard title="Zodiac and calendar" href="/en/chinese/zodiac/" description="Three animals, the lunar date, the twenty-four terms." />
  <LinkCard title="Zi Wei Dou Shu" href="/en/chinese/ziwei/" description="Star placement, the twelve palaces and four school switches." />
  <LinkCard title="Conventions" href="/en/chinese/conventions/" description="Four axes and a run against an external dataset." />
  <LinkCard title="Questions we get" href="/en/chinese/faq/" description="Unknown birth time, true solar time, the state of Zi Wei." />
  <LinkCard title="Flying stars" href="/en/feng-shui/flying-star/" description="Nine palaces, period, sitting and facing." />
</CardGrid>