# API паранів зірка-планета

Зірка й планета в парані тоді, коли обидві стоять на кутах одночасно, а чи можливо це взагалі, залежить тільки від широти. Тому паран це широта, і саме так його подає Бернадетт Брейді, і цей ендпоінт повертає широти, а не точки. Доступні 953 зірки, 36 у наборі за замовчуванням.

## Ендпоінт

`POST /v1/parans/star`

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

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

Для кожної пари зірка-планета ендпоінт бере чотири кутові події (схід, захід, кульмінація, антикульмінація) і питає, на якій широті дві з них припадають на той самий місцевий зоряний час. Кульмінація фіксує зоряний час на прямому сходженні тіла; схід і захід зсувають його на піводенну дугу, яка залежить від широти й схилення. Кожна з дванадцяти пар подій розв'язується, і кожен корінь повертається з широтою, зоряним часом і меридіаном, де пара стоїть на кутах саме в цей момент карти. Меридіан проти меридіана відкидається: у цій умові широти немає взагалі, тож вона або не виконується ніколи, або виконується всюди, а «всюди» означає лише спільне пряме сходження. Зірки, які обчислилися, але нічого не дали, названі у відповіді, а не викинуті мовчки, і саме це стається з навколополярною зіркою на кшталт Полярної майже на всьому діапазоні.

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

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

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

| 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) | no | UTC offset in effect at the birth moment. Defaults to 0. |
| `stars` | string[] | no | Star names from the Swiss Ephemeris catalogue. Defaults to the 36-star astrological set. The full list is at GET /v1/fixed-stars/catalog. |
| `planets` | number[] | no | Swiss Ephemeris planet ids. Defaults to 0-9, Sun through Pluto. |
| `latitudeLimit` | number (degrees) | no | Search range either side of the equator. Defaults to 60, the range Brady tabulates. |
| `horizon` | "geometric" | "apparent" | no | Which horizon counts as rising. Geometric (default) is altitude 0; apparent is -34 arcmin, where refraction lifts a body into view first. Worth about two degrees of paran latitude at mid-latitudes. |

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

```bash
curl -X POST https://api.astroway.info/v1/parans/star \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "date": "1990-05-15",
  "time": "14:30:00",
  "timezoneOffset": 3,
  "stars": ["Regulus", "Sirius"],
  "planets": [0, 4]
}'
```

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

```json
{
  "ok": true,
  "data": {
    "type": "star-parans",
    "horizon": "geometric",
    "latitudeLimit": 60,
    "count": 16,
    "stars": [
      { "name": "Regulus", "magnitude": 1.36, "rightAscension": 151.9686, "declination": 12.0133 }
    ],
    "parans": [
      {
        "star": "Regulus",
        "starEvent": "rise",
        "planetId": 0,
        "planetName": "Sun",
        "planetEvent": "culminate",
        "latitude": 39.1022,
        "longitude": 6.5735,
        "lst": 51.6
      }
    ]
  }
}
```

## Нотатки

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

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

- https://api.astroway.info/astrology-api/parans/
- https://api.astroway.info/astrology-api/fixed-stars/
- https://api.astroway.info/astrology-api/astrocartography/
- https://api.astroway.info/astrology-api/relocated-chart/

---

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