# API лунара

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

## Ендпоінт

`POST /v1/lunar-return`

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

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

Ендпоінт лунара зчитує точну довготу натального Місяця з переданих даних народження, а потім шукає вперед від заданої початкової дати першу мить, коли транзитний Місяць повертається до тієї самої довготи. Оскільки Місяць завершує сидеричний цикл приблизно за 27,3 дня, це повернення припадає приблизно раз на місяць. Ендпоінт перетворює знайдену мить на юліанський день, бере геоцентричні позиції й швидкості з рушія 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). |
| `afterDate` | string (YYYY-MM-DD) | yes | Required start date (YYYY-MM-DD); the endpoint finds the first lunar return on or after it. |
| `afterTime` | string (HH:MM:SS) | no | Optional clock time of the start point (HH:MM:SS). |
| `afterTzOffset` | number (hours) | no | Optional UTC offset for the start point, in hours. |
| `locationLat` | number | no | Optional latitude in decimal degrees to relocate the return chart, north positive. |
| `locationLng` | number | no | Optional longitude in decimal degrees to relocate the return chart, east positive. |

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

```bash
curl -X POST https://api.astroway.info/v1/lunar-return \
  -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,
  "afterDate": "2026-06-15"
}'
```

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

```json
{
  "ok": true,
  "data": {
    "input": {},
    "planets": [
      {
        "name": "Moon",
        "longitude": 282.7,
        "sign": "Capricorn",
        "house": 6
      }
    ],
    "houses": {
      "ascendant": 201.5,
      "mc": 110.3,
      "cusps": [
        "…"
      ]
    },
    "aspects": [
      "…"
    ]
  }
}
```

## Нотатки

Ендпоінт повертає наступне одне повернення на чи після заданої дати, а не серію — викликайте повторно, просуваючи початкову дату, щоб побудувати послідовність. Цифра ~27,3 дня — це сидеричний місяць, тож повернення зміщуються відносно календаря. Якщо місце не передано, карта будується для натального місця; перевизначення релокує лише кути й доми. Скрізь тропічний зодіак і Swiss Ephemeris.

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

- https://api.astroway.info/astrology-api/solar-return/
- https://api.astroway.info/astrology-api/transits/

---

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