# API астрокартографії

Астрокартографія бере один момент народження й проєктує його на всю планету: замість питання, де планети були в небі, вона питає, де на Землі кожна планета стояла на куті. Ендпоінт повертає геометрію ліній, яку ви наносите на карту світу, щоб побачити, які довготи активують яку планетну енергію.

## Ендпоінт

`POST /v1/astrocartography`

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

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

За датою народження, часом, зсувом UTC та координатами ендпоінт фіксує точне небо цієї миті, а потім обходить земну кулю, шукаючи кожен меридіан і криву, де планета стояла на одному з чотирьох кутів. Для кожної з десяти планет та вузлів він простежує чотири родини ліній: лінію сходу, де тіло було на Асценденті, лінію заходу на Десценденті, лінію кульмінації на Середині неба та лінію антикульмінації на Глибині неба. Лінії MC та IC проходять як чисті меридіани; лінії AC та DC згинаються у криві, залежні від широти, адже тіло, що сходить точно на сході на одній широті, на іншій сходить далеко на північ чи південь. Усе повертається як серіалізована геометрія ліній у data.lines, готова до передавання в картографічну бібліотеку. Це релокаційна техніка, яку популяризував Джим Льюїс як Astro*Carto*Graphy.

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

Звертайтеся до цього ендпоінта, коли змінною є місце і ви хочете знати, як карта перевиражає себе на мапі — для порад щодо релокації, інструментів подорожей і вибору місця життя чи будь-якої функції, що накладає карту людини на глобус. Це природний бекенд для інтерактивної мапи: запросіть лінії один раз для моменту народження, відрендеріть їх як полілінії й дайте користувачеві панорамувати континенти, читаючи, яка планета керує яким коридором. Оскільки вивід — це чиста геометрія, а не текст, він охайно поєднується з вашим власним стилюванням, кластеризацією та шарами «клік-для-інтерпретації» на фронтенді. Поєднуйте його з викликом natal-chart, коли хочете бачити поруч і структуру домашньої карти, і релоковані лінії; обидва поділяють те саме розв'язання моменту народження, тож планетні позиції за мапою збігаються точно.

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

| 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/astrocartography \
  -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": {
    "lines": [
      {
        "planet": "Venus",
        "type": "MC",
        "longitude": 14.2
      },
      {
        "planet": "Jupiter",
        "type": "AC",
        "points": [
          "…"
        ]
      }
    ]
  }
}
```

## Нотатки

Позиції беруться зі Swiss Ephemeris (Astrodienst), скомпільованого у WASM — того самого рушія, що стоїть за натальними ендпоінтами, тож лінії прив'язані до ідентичних довгот планет. Кутовість обчислюється у тропічному зодіаку. Відповідь несе лише геометрію — малювання, проєкцію та стилювання карти світу лишено вашому клієнту.

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

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

---

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