# API геліоцентричної карти

Переносить спостерігача на Сонце. Замість звичного небосхилу із центром на Землі ендпоінт повертає Сонячну систему такою, якою її видно із Сонця — Земля стає тілом, Місяць і Асцендент зникають, а кожна планета подається в геліоцентричній довготі. Передайте момент — отримаєте геліоцентричну карту. Точність Swiss Ephemeris, відповідь у JSON.

## Ендпоінт

`POST /v1/heliocentric`

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

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

Геліоцентричний ендпоінт перетворює передані дату, час і зсув UTC на юліанський день, а потім запитує у рушія Swiss Ephemeris позиції планет, віднесені до центру Сонця, а не Землі. У цьому каркасі Земля постає як тіло на орбіті зі своєю довготою, тоді як Місяць — що обертається навколо Землі, а не Сонця — і геоцентричні Асцендент і Середина неба не мають сенсу й опускаються. Відповідь повертає геліоцентричні довготи планет і повну сітку аспектів, обчислену між ними, із позначками наближення й розходження та точними орбісами. Оскільки геліоцентричний рух рівномірний і вільний від ретроградних петель і паралаксу, які вносить власна орбіта Землі, відстані між планетами читаються зовсім інакше, ніж у геоцентричній карті — позиції відображають справжню орбітальну геометрію навколо Сонця.

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

Звертайтеся до геліоцентричної карти в дослідницьких, фінансових і мунданних контекстах, де погляд із центром на Сонці є аналітичним стандартом — моделі ринкового таймінгу, що відстежують геліоцентричні кути планет, мунданні дослідження планетних циклів чи будь-який аналіз, якому потрібна орбітальна геометрія без спотворень геоцентричної ретроградності. Вона також корисна як контрастне накладення на звичайну карту, адже планета, що виглядає ретроградною із Землі, тут просто рухається вперед навколо Сонця. Оскільки тут немає Місяця, Асцендента й домів у геоцентричному сенсі, сприймайте вихідні дані як набір планетних довгот і аспектів, а не як особисту натальну карту — вона відповідає на питання про цикли й конфігурації, а не про знак, що сходить, у конкретної людини.

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `date` | string (YYYY-MM-DD) | yes | Birth date. |
| `time` | string (HH:MM:SS) | yes | Local clock time at birth. |
| `timezoneOffset` | number (hours) | yes | UTC offset in effect at the birth moment (e.g. 3 for Kyiv summer time). Decimal allowed for half-hour zones. |
| `latitude` | number | yes | Birth-place latitude, decimal degrees (north positive). |
| `longitude` | number | yes | Birth-place longitude, decimal degrees (east positive). |

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

```bash
curl -X POST https://api.astroway.info/v1/heliocentric \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "date": "1990-05-15",
  "time": "14:30:00",
  "timezoneOffset": 3,
  "latitude": 50.45,
  "longitude": 30.52
}'
```

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

```json
{
  "ok": true,
  "data": {
    "input": {},
    "planets": [
      {
        "name": "Earth",
        "longitude": 234.2
      },
      {
        "name": "Mars",
        "longitude": 9.1
      }
    ],
    "aspects": [
      {
        "planet1": "Earth",
        "planet2": "Jupiter",
        "type": "trine",
        "orb": 0.9
      }
    ]
  }
}
```

## Нотатки

Це каркас із центром на Сонці: Земля повертається як тіло, а Місяць, геоцентричні Асцендент і Середина неба відсутні за побудовою. Ретроградний рух зникає, бо він є артефактом спостереження з рухомої Землі. Вихідні дані найкраще читати як геліоцентричні довготи плюс їхню сітку аспектів для роботи з циклами й мунданної астрології, а не як особисту карту. Скрізь тропічні довготи й Swiss Ephemeris.

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

- https://api.astroway.info/astrology-api/draconic-chart/
- https://api.astroway.info/astrology-api/natal-chart/

---

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