# API Zi Wei Dou Shu (Пурпурна зірка)

Дата, час і стать дають карту цілком: дванадцять дворців зі своїми стовбурами, усі чотирнадцять головних зірок, допоміжні, тридцять одну малу, дванадцять стадій, десятирічні межі і чотири перетворення, позначені прямо на зірках, які їх несуть.

## Ендпоінт

`POST /v1/ziwei/chart`

- Operation ID: `ziwei/chart`
- Вартість: 20 кредитів (тариф 2)
- Типова латентність: 130 мс, заміряно на проді
- Канонічна сторінка: https://api.astroway.info/astrology-api/ziwei-doushu/

## Що обчислює

Народження зводиться до місячної дати, бо 斗數 суто місячна система і, на відміну від BaZi, на сонячні терміни не переходить. З місячного місяця і стражі ендпоінт ставить дворець Життя і дворець Тіла, далі дає кожному дворцю стовбур за правилом п'яти тигрів і читає 五行局 зі стовпа дворця Життя. Це число разом із місячним днем ставить 紫微 за класичним правилом ділення з позикою, шість зірок його ряду йдуть фіксованими зміщеннями, 天府 дзеркалить його навколо осі 寅-申 і несе свої вісім. Поверх цього скелета лягають шість щасливих і шість лихих зірок, 祿存 і 天馬, тридцять одну малу зірку від стовбура року, гілки року, місяця, дня і стражі, дванадцять стадій, цикли 博士, 將前 і 歲前, десятирічні межі, що відкриваються на числі 局, і річна межа, якщо передати вік. Чотири перетворення визначаються стовбуром року і кріпляться до самих зірок, а не віддаються окремим списком.

## Коли використовувати

Беріть, коли будуєте продукт китайської астрології для ринку, який читає будь-якою мовою, крім китайської: застосунок, сервіс читань, малювальник карт, агент, якому потрібна структура до інтерпретації. Відповідь це чиста структура без прози, тож вона однаково добре лягає в сітку дванадцяти дворців, у генератор звіту і в промт до моделі. Довідкові ендпоінти тієї самої родини дешевші й корисні для словника і підказок, але віддають ту саму таблицю будь-якому народженню і прямо про це кажуть полем, тож карту з них будувати не треба.

## Параметри запиту

| Parameter | Type | Required | Description |
|---|---|---|---|
| `date` | string (YYYY-MM-DD) | yes | Birth date. It is converted to a lunar date, because Zi Wei is a lunar system. |
| `time` | string (HH:MM:SS) | yes | Local clock time. Required: the soul palace is placed from the double-hour, so a chart without it would be twelve palaces of confident nonsense rather than a partial answer. |
| `gender` | string | yes | male or female. It sets the direction of the twelve life stages, the scholar cycle and the decade limits, so the chart cannot be built without it. |
| `age` | number | no | Return the annual-limit palace for this age. Omit and the field comes back null. |
| `yearDivide` | string | no | lunar (default: the year opens on day one of the first lunar month) or lichun (the BaZi boundary, for reconciling against a calculator that imported it). |
| `fixLeap` | boolean | no | Split a leap month at day 15 (default) or count the whole of it as the month it follows. |
| `dayDivide` | string | no | forward (default: 23:00 belongs to the next day) or current (keep the date and mark the hour as the late Zi). |
| `school` | string | no | The 四化 table: zhongzhou (default), quanji, quanshu or beipai. The four disagree on three of the ten year stems. |
| `language` | string | no | Any of 21 codes. Palace names and life-stage names come back translated; star names stay as characters with an English gloss. |

## Приклад запиту

```bash
curl -X POST https://api.astroway.info/v1/ziwei/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2000-08-16",
    "time": "04:00:00",
    "gender": "male",
    "age": 25
  }'
```

## Приклад відповіді

```json
{
  "ok": true,
  "data": {
    "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" }],
        "lifeStage": { "chinese": "死", "name": "Death" },
        "decade": { "index": 0, "fromAge": 3, "toAge": 12 }
      }
    ]
  }
}
```

## Нотатки

Пришпилено до трьох опублікованих карт, а не до однієї бібліотеки, і це навмисно: майже вся відкрита екосистема Zi Wei походить від одного проєкту, тож збіг з кількома це збіг з одним. Дві повні карти відтворюються точно, третя взята з навчального тексту без стосунку до них. Чотири перемикачі школи живуть у тілі запиту, а не в нашому коді, бо кожен зсуває карту цілком для тих народжень, яких торкається: межа року, високосний місяць, межа доби о 23:00 і таблиця перетворень. Коли інший калькулятор дає інше, перевіряйте спершу ці чотири, а не арифметику.

## Пов’язані техніки

- https://api.astroway.info/astrology-api/bazi-chart/
- https://api.astroway.info/astrology-api/true-solar-time/
- https://api.astroway.info/astrology-api/chinese-zodiac-compatibility/

---

Повна машиночитана специфікація: https://api.astroway.info/v1/openapi.json
Інструкції для агента: https://api.astroway.info/AGENTS.md