# API транзитної карти

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

## Ендпоінт

`POST /v1/transits`

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

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

Ендпоінт транзитів приймає натальні дані людини — дату народження, час, зсув UTC, широту, довготу й систему домів — та окремий цільовий момент. Він перетворює цю цільову дату й час на юліанський день, запитує у рушія Swiss Ephemeris геоцентричну довготу, широту й швидкість кожного транзитного тіла, а потім розкладає ці позиції по домах, побудованих для натального розташування. У відповіді — транзитні планети зі своїми знаками й положеннями в домах, куспіди натальних домів і повна сітка аспектів, обчислена між самими транзитними тілами, кожен із позначкою наближення чи розходження та точним орбісом. Також повертаються паралельні та антисційні (дзеркальні) аспекти для роботи зі схиленням і сонцестоянською віссю. Ретроградний рух позначається за швидкістю тіла, тож видно, які транзити прямі, стаціонарні чи рухаються назад у запитаний момент.

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

Використовуйте це, коли потрібне все небо таким, яким воно лежить над чиєюсь картою певного дня — віджет щоденних транзитів, панель у стилі «що зараз над головою» або сирий каркас, який ШІ-агент читає перед описом поточного астрологічного клімату. Оскільки ендпоінт повертає транзитну карту на каркасі натальних домів, а не вибраний список контактів транзит-до-наталу, він доречний, коли потрібен сам структурний знімок. Якщо ж вам потрібні точно датовані попадання транзит-до-наталу за діапазон дат — точні дати, інгресії, точки стоянки — зверніться до ендпоінта transit-calendar, створеного саме для цієї задачі таймінгу. Поєднуйте обидва: цей ендпоінт для карти на момент часу, календар для переліку майбутніх подій.

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

| 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). |
| `transitDate` | string (YYYY-MM-DD) | yes | Required target date for the transit snapshot (YYYY-MM-DD). |
| `transitTime` | string (HH:MM:SS) | no | Optional clock time of the transit moment (HH:MM:SS). |
| `transitTzOffset` | number (hours) | no | Optional UTC offset for the transit moment, in hours. |

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

```bash
curl -X POST https://api.astroway.info/v1/transits \
  -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,
  "transitDate": "2026-06-15",
  "transitTime": "12:00:00",
  "transitTzOffset": 3
}'
```

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

```json
{
  "ok": true,
  "data": {
    "input": {},
    "julianDay": 2461206.875,
    "planets": [
      {
        "name": "Sun",
        "longitude": 84.29,
        "sign": "Gemini",
        "house": 11
      }
    ],
    "houses": {
      "ascendant": 160.4,
      "mc": 70.1,
      "cusps": [
        "…"
      ]
    },
    "aspects": [
      {
        "planet1": "Sun",
        "planet2": "Moon",
        "type": "conjunction",
        "orb": 1.2,
        "applying": true
      }
    ],
    "parallelAspects": [
      "…"
    ],
    "antiscia": [
      "…"
    ]
  }
}
```

## Нотатки

Уточнюємо обсяг: ендпоінт повертає транзитну карту, накладену на каркас натальних домів, а не попередньо відфільтрований список аспектів транзит-до-наталу. Сітка аспектів обчислюється між транзитними тілами, а не між транзитними й натальними точками. Для таймінгу до-наталу за діапазон дат використовуйте /transit-calendar. Скрізь тропічний зодіак і Swiss Ephemeris.

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

- https://api.astroway.info/astrology-api/secondary-progressions/
- https://api.astroway.info/astrology-api/ai-horoscope/

---

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