# API нерухомих зір

Поза рухомими планетами лежить давніший шар астрології — нерухомі зорі: Регул, Спіка, Алголь, Альдебаран та їхні побратими. Цей ендпоінт перевіряє натальну карту на щільні з'єднання з цими великими зорями й повертає кожен контакт із його орбісом, щоб ви могли вплести репутований характер зорі у читання.

## Ендпоінт

`POST /v1/fixed-stars`

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

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

За наданими датою народження, часом, зсувом UTC та координатами ендпоінт обчислює натальні точки, а потім проходить каталог великих нерухомих зір із традиції Вівіан Робсона та Птолемея — яскраві, астрологічно вагомі зорі, а не все небо. Для кожної зорі він перевіряє натальні точки на з'єднання, і там, де воно потрапляє в орбіс, записує контакт разом із точним орбісом відстані. Вивід у data.stars — це перелік влучань «зоря-точка»: яка зоря, якої натальної точки вона торкається й наскільки тісне вирівнювання, тож з'єднання у пів градуса читається потужнішим за те, що на краю орбіса. Розглядаються лише з'єднання — техніка вважає зорю значущою, коли точка карти стоїть на ній, а не коли вона утворює довготні кути, які планети роблять одна з одною. Це виявляє іменовані зорі, що класичні джерела виокремлювали як щасливі чи небезпечні, готові до зіставлення з вашим власним текстом про значення зір.

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

Звертайтеся до цього ендпоінта, коли читанню карти потрібна додаткова фактура іменованих зір — для традиційного інтерпретатора з урахуванням нерухомих зір, генератора звітів, що відзначає вражаючий контакт з Алголем чи царським Регулом, або освітнього інструмента, що навчає лору за найяскравішими зорями. Дизайн із вузьким орбісом і лише з'єднаннями тримає вивід сфокусованим: ви отримуєте жменю контактів, вартих згадки, а не шум, що легко відрендерити коротким виділеним переліком. Передайте ті самі дані народження, що й ендпоінту 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/fixed-stars \
  -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": {
    "stars": [
      {
        "star": "Regulus",
        "point": "Mercury",
        "orb": 0.4
      },
      {
        "star": "Algol",
        "point": "Mars",
        "orb": 1.1
      }
    ]
  }
}
```

## Нотатки

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

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

- https://api.astroway.info/astrology-api/essential-dignities/
- https://api.astroway.info/astrology-api/arabic-parts/

---

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