# API соляра

Будує карту на точну мить, коли Сонце повертається до свого натального градуса в обраному році — астрологічний день народження. Передайте натальну карту й рік — отримаєте карту соляра для цього циклу. Тропічний, Сонце-до-натального-Сонця, точність Swiss Ephemeris, відповідь у JSON.

## Ендпоінт

`POST /v1/solar-return`

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

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

Ендпоінт соляра спершу зчитує точну зодіакальну довготу натального Сонця з переданих даних народження, а потім шукає в заданому році точну мить, коли транзитне Сонце повертається до тієї самої довготи — зазвичай у межах доби від календарного дня народження. Він перетворює цю мить повернення на юліанський день, бере геоцентричні позиції й швидкості з рушія 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). |
| `year` | number | yes | Required integer year in which to find the Sun's return to its natal longitude. |

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

```bash
curl -X POST https://api.astroway.info/v1/solar-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,
  "year": 2026
}'
```

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

```json
{
  "ok": true,
  "data": {
    "input": {},
    "planets": [
      {
        "name": "Sun",
        "longitude": 54.23,
        "sign": "Taurus",
        "house": 9
      }
    ],
    "houses": {
      "ascendant": 188.2,
      "mc": 95,
      "cusps": [
        "…"
      ]
    },
    "aspects": [
      "…"
    ]
  }
}
```

## Нотатки

Повернення підбирається тропічно, Сонце до натального Сонця, без корекції на прецесію за замовчуванням, тож воно відображає звичайний західний соляр, а не сидерично скоригований варіант. Карта будується для переданого натального місця; релокаційні соляри вимагали б перерахунку в іншому місці. Скрізь тропічний зодіак і Swiss Ephemeris.

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

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

---

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