# API локального простору

Локальний простір ставить інше питання, ніж астрокартографія: не де на Землі планета була на куті, а в якому напрямку компаса вона стояла від місця народження. Ендпоінт повертає азимут і висоту для кожного тіла та шлях великого кола, який цей напрямок креслить по земній кулі.

## Ендпоінт

`POST /v1/local-space`

- Operation ID: `local-space`
- Вартість: 50 кредитів (тариф 3)
- Типова латентність: 216 мс, заміряно на проді
- Канонічна сторінка: https://api.astroway.info/astrology-api/local-space/

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

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

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

Використовуйте локальний простір, коли продукт про напрямок і відстань від фіксованого дому, а не про абсолютну позицію на глобусі. Домінують два випадки. Перший це релокація в будь-якому масштабі, від вибору міста вздовж сприятливого пеленга до рішення, куди рухатися в межах однієї країни, адже велике коло від місця народження перетинає значно більше придатної території, ніж жменя астрокартографічних меридіанів. Другий це робота з інтер'єром і ділянкою, де ті самі азимути читаються в масштабі кімнати всередині житла: ендпоінт повертає пеленги, а супутній /local-space/influence-zone перетворює будь-який із них на полігон конуса, який можна намалювати. Якщо ви вже рендерите астрокартографію, додати локальний простір це найдешевший спосіб подвоїти глибину релокаційної функції, бо він використовує той самий вхід і ту саму мапу.

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

| 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. Decimal allowed for half-hour zones. |
| `latitude` | number | yes | Birth-place latitude, decimal degrees (north positive). Local space is anchored here, so this is not optional. |
| `longitude` | number | yes | Birth-place longitude, decimal degrees (east positive). |

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

```bash
curl -X POST https://api.astroway.info/v1/local-space \
  -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": {
    "birthplace": { "latitude": 50.45, "longitude": 30.52 },
    "count": 13,
    "lines": [
      {
        "planetId": 0,
        "planetName": "Sun",
        "azimuth": 219.8018,
        "altitude": 53.1309,
        "color": "#FFB300",
        "points": [{ "lat": 50.45, "lng": 30.52 }, "…"]
      }
    ]
  }
}
```

## Нотатки

Позиції беруться зі Swiss Ephemeris (Astrodienst), скомпільованого у WASM. Азимут вимірюється за годинниковою стрілкою від істинної, а не магнітної півночі, тож поправка на схилення не застосовується й не потрібна. Шлях великого кола повертається семплованими координатами, а не формулою, що звільняє клієнт від сферичної геометрії. Техніку в цьому вигляді розробив Майкл Ерлевайн, вона описана в його Astrophysical Directions.

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

- https://api.astroway.info/astrology-api/astrocartography/
- https://api.astroway.info/astrology-api/parans/
- https://api.astroway.info/astrology-api/relocated-chart/

---

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