# API річних профекцій

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

## Ендпоінт

`POST /v1/profections`

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

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

Ендпоінт бере дані народження й цільову дату, рахує повні роки від моменту народження і просуває по одному цілому знаку від асценденту за кожен із них. Відповідь віддає порахований вік, індекс знака (від нуля), на який випав рік, і планету-управителя цього знака в полі lordOfYear, а поруч натальні асцендент, MC, Сонце й Місяць, щоб ви змалювали рік на тлі карти без другого виклику. Номер дому виводиться просто з віку: цикл дванадцятирічний, тож профекційний дім дорівнює віку за модулем дванадцять плюс один. Вік 36 повертає до першого дому, а отже до власного знака асценденту, і саме тому приклад із асцендентом на 169.97 градуса в Діві віддає signIndex 5 і Меркурія як управителя того року. Оскільки відлік іде від моменту народження, а не від календаря, профекційний рік обертається на день народження, а не першого січня.

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

Беріть профекції, коли потрібен шар таймінгу, зрозумілий читачеві без ефемерид. Кожен рік має одну керівну планету, тож річний прогноз, звіт до дня народження чи AI-наратив можна побудувати навколо одного чіткого твердження, а не таблиці транзитів. Техніка добре складається з транзитами й поверненнями: знайдіть тут управителя року, подивіться, що відбувається з цією планетою транзитом, і ви маєте класичне двокрокове прочитання за два виклики. Вона також пасує до солярного повернення, що покриває той самий рік з іншого боку. Техніка навмисно груба: вона каже, який відділ життя активовано і хто ним керує, а не що станеться конкретного дня, тож тримайте її за раму, на яку навішується точніший таймінг.

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

| 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. |
| `latitude` | number | yes | Birth-place latitude, decimal degrees (north positive). |
| `longitude` | number | yes | Birth-place longitude, decimal degrees (east positive). |
| `targetDate` | string (YYYY-MM-DD) | yes | The date whose profection year you want. Age is counted from the birth moment, so the year turns on the birthday, not on January 1. |

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

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

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

```json
{
  "ok": true,
  "data": {
    "age": 36,
    "signIndex": 5,
    "lordOfYear": "Mercury",
    "ascendant": 169.9680,
    "mc": 77.0743,
    "sun": 54.3760,
    "moon": 296.9047
  }
}
```

## Нотатки

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

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

- https://api.astroway.info/astrology-api/natal-chart/
- https://api.astroway.info/astrology-api/solar-return/
- https://api.astroway.info/astrology-api/essential-dignities/

---

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