# API сумісності за китайським зодіаком

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

## Ендпоінт

`POST /v1/chinese/zodiac/compatibility`

- Operation ID: `chinese/zodiac/compatibility`
- Вартість: 10 кредитів (тариф 1)
- Типова латентність: 60 мс, заміряно на проді
- Канонічна сторінка: https://api.astroway.info/astrology-api/chinese-zodiac-compatibility/

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

Кожна дата зводиться до свого сонячного року, який відкриває мить Lichun, взята з ефемерид, а не 1 січня і не китайський Новий рік. Цей рік дає земну гілку і її тварину. Далі оцінка читає відношення між двома гілками: 三合, чотири трійки гілок, рівномірно розставлені по колу, і 六冲, шість пар протилежних гілок. Сусідні і нейтральні відношення лягають між ними. Відповідь віддає обидві визначені тварини, число, категорію і коротку примітку, тож інтерфейс покаже вердикт без другої таблиці.

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

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

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `person1.date` | string (YYYY-MM-DD) | yes | First birth date. The animal comes from the solar year, which opens at Li Chun, not at New Year. |
| `person2.date` | string (YYYY-MM-DD) | yes | Second birth date. |
| `person1.time` | string (HH:MM:SS) | no | Only matters for a birth within a day of Li Chun, where the hour decides the year. |
| `person1.timezoneOffset` | number (hours) | no | The UTC offset the clock was on. Used with time to place a boundary birth. |
| `person1.solarYear` | number | no | Override the resolved year outright when you already hold it. |
| `language` | string | no | Any of 21 codes. Adds animalName next to the English token; the English fields do not move. |

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

```bash
curl -X POST https://api.astroway.info/v1/chinese/zodiac/compatibility \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "person1": { "date": "1990-05-15" },
    "person2": { "date": "1988-02-20" }
  }'
```

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

```json
{
  "ok": true,
  "data": {
    "person1": { "solarYear": 1990, "animal": "Horse" },
    "person2": { "solarYear": 1988, "animal": "Dragon" },
    "compatibility": {
      "score": 65,
      "category": "good",
      "notes": ["Compatible enough; complementary differences."]
    }
  }
}
```

## Нотатки

Оцінка виведена з канонічної доктрини 三合 і 六冲, а не з написаної від руки матриці думок, тому вона відтворювана і пояснює себе. Народження в межах доби від Lichun це єдиний випадок, де важлива година: надішліть time і timezoneOffset, і межа розв'яжеться з точністю до секунди. Назви тварин перекладаються на 21 мову, англійський токен лишається на місці.

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

- https://api.astroway.info/astrology-api/bazi-chart/
- https://api.astroway.info/astrology-api/synastry/
- https://api.astroway.info/astrology-api/true-solar-time/

---

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