# API китайської метафізики

**53 ендпоінти** на чотири родини: BaZi (18), китайський календар і зодіак (15), Zi Wei Dou Shu (14) та I Ching (6). Календар виведений з ефемерид, а не з таблиць дат, тому працює на роки з 2 по 2899 і не залежить від того, чи хтось оновив довідник.

## Що входить

| Родина | Ендпоінтів | Стан |
|---|---:|---|
| BaZi: стовпи і аналіз | 18 | Повний класичний апарат |
| Календар, зодіак, фен-шуй, Тун Шу | 15 | Виведений з ефемерид |
| Zi Wei Dou Shu | 14 | Розстановка зірок рахується, одинадцять довідників лишаються довідниками |
| I Ching | 6 | Гексаграми, кидок монет, змінні риски |

## Чим це відрізняється від безкоштовної бібліотеки

Чесна відповідь: якщо потрібні тільки чотири стовпи, беріть `lunar-typescript`. Він під MIT, рахує у вашому процесі, офлайн, без обмежень частоти, і платити за це не треба.

Різниця починається там, де бібліотека закінчується.

| Що | Бібліотеки під MIT | AstroWay API |
|---|---|---|
| Чотири стовпи, 藏干, 纳音, 十神 | так | так |
| 神煞 з обома читаннями там, де школи розходяться | ні | так |
| Взаємодії гілок 刑冲合害 | ні | так |
| Сила денного господаря в рамці 扶抑 | ні | так |
| Істинний сонячний час як окремий розрахунок | ні | так |
| Летючі зірки за сидінням і фасадом, число Гуа | ні | так |
| Вибір дати Тун Шу з фільтром по діяльності | ні | так |
| Двадцять одна мова | ні | так |
| Одна конвенція для PHP, JavaScript і Python одночасно | ні | так |

Останній рядок і є тим, за що зазвичай платять. Команда, у якої сайт на PHP, застосунок на JavaScript і крони на Python, інакше тримає три реалізації межі року і рано чи пізно отримує три різні відповіді на одну дату народження.

## Конвенції названі вголос

Чотири осі, на яких калькулятори розходяться, і жодна з них не помилка. Більшість реалізацій вибирає мовчки; ми пишемо вибір у відповідь і тримаємо [сторінку конвенцій](/chinese/conventions/) з прогоном по зовнішньому CC0-датасету.

| Вісь | Наша відповідь |
|---|---|
| Межа року | 立春 Lichun, точна мить з ефемерид |
| Межа доби | 23:00, ранній 子時 належить наступному дню |
| Істинний сонячний час | вимкнено за замовчуванням, вмикається прапорцем |
| Літній час | розв'язується `timezoneOffset`, який надсилає клієнт |

## Приклад

<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="Типізовані методи">
Аналітичні маршрути BaZi з'явилися пізніше за поточний реліз SDK, тому типізованих методів `aw.bazi.chart(...)` поки немає. Приклади вище використовують сирий клієнт, який працює з будь-яким шляхом уже сьогодні. Типізовані обгортки приїдуть з наступним релізом SDK.
</Aside>

## Мови

Тварини, стихії, інь і ян, палаци і дванадцять стадій перекладені на 21 мову. Додайте `?lang=es`, і поруч з англійським токеном з'явиться поле `*Name`. Англійські поля не змінюються ніколи: локалізація додає, а не замінює.

Стовбури, гілки, назви зірок і 纳音 навмисно не перекладаються: їхнє міжнародне ім'я це піньїнь поруч з ієрогліфом.

## Розділи документації

<CardGrid>
  <LinkCard title="Огляд" href="/chinese/" description="Що рахується, чого немає і чому." />
  <LinkCard title="BaZi: чотири стовпи" href="/chinese/bazi/" description="Вісімнадцять ендпоінтів і п'ять місць, де школи розходяться." />
  <LinkCard title="Зодіак і календар" href="/chinese/zodiac/" description="Три тварини, місячна дата, двадцять чотири терміни." />
  <LinkCard title="Zi Wei Dou Shu" href="/chinese/ziwei/" description="Розстановка зірок, дванадцять дворців і чотири перемикачі школи." />
  <LinkCard title="Конвенції" href="/chinese/conventions/" description="Чотири осі і прогін по зовнішньому датасету." />
  <LinkCard title="Часті питання" href="/chinese/faq/" description="Невідомий час народження, істинний сонячний час, стан Zi Wei." />
  <LinkCard title="Летючі зірки" href="/feng-shui/flying-star/" description="Дев'ять палаців, період, сидіння і фасад." />
</CardGrid>