# API есенціальних гідностей

Есенціальні гідності вимірюють, наскільки комфортно кожна планета почувається у знаку й градусі, який вона займає. Ендпоінт проводить кожне тіло крізь п'ятиступеневу традиційну схему — обитель, екзальтацію, тригон, терм і лице — разом із двома слабкостями й повертає і розбивку по планетах, і єдиний зважений підсумок.

## Ендпоінт

`POST /v1/essential-dignities`

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

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

За моментом і місцем народження ендпоінт визначає кожну планету за знаком і градусом, а потім оцінює її за птолемеївськими таблицями гідностей, які успадкувала середньовічна та елліністична практика. Він перевіряє п'ять есенціальних гідностей за спадом сили — обитель, екзальтацію, тригональне управління для секти карти, терм (межу), у який потрапляє градус, та лице (декан) — і дві есенціальні слабкості, вигнання й падіння, де планета стоїть навпроти своєї обителі чи екзальтації. Кожна планета отримує умовні бали гідності за кожну умову, яку виконує, слабкості віднімаються, а цифри зводяться у розбивку по тілах у data.dignities плюс загальносхемний totalScore. Результат каже не лише, у якому знаку планета, а наскільки вона там гідна чи послаблена, відрізняючи планету у власній обителі від тієї, що лише проходить крізь знак, на який не має жодних прав.

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

Звертайтеся до цього ендпоінта, коли інтерпретації потрібно зважувати силу планет, а не просто звітувати про положення — для традиційних та елліністичних читань карти, горарних помічників, оцінювання елекцій чи будь-якого інструмента, що ранжує, які планети справді тримають карту. Загальний бал дає швидкий скаляр для сортування чи порогів, а рядки по планетах дозволяють пояснити чому: ця Венера екзальтована й у тригоні, той Марс у падінні та вигнанні. Він природно поєднується з ендпоінтом 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/essential-dignities \
  -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": {
    "dignities": [
      {
        "planet": "Venus",
        "rulership": false,
        "exaltation": true,
        "triplicity": true,
        "score": 7
      }
    ],
    "totalScore": 12
  }
}
```

## Нотатки

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

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

- https://api.astroway.info/astrology-api/arabic-parts/
- https://api.astroway.info/astrology-api/fixed-stars/

---

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