# API гармонічних карт

Гармонічна карта множить довготу кожної планети на ціле число й загортає результат назад у коло. Арифметика тривіальна, а ефект ні: аспекти, які незручно розгледіти в натальній карті, стають з'єднаннями в гармонічній, і візерунок, у який ви вдивлялися, постає стосом.

## Ендпоінт

`POST /v1/harmonics`

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

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

Надішліть дані народження й номер гармоніки від 2 до 36. Ендпоінт рахує натальні положення, множить кожну довготу на гармоніку, бере залишок від 360 і віддає отриману карту з власною сіткою аспектів. Приклад показує арифметику наочно: натальне Сонце на 54.3760 градуса у п'ятій гармоніці повертається як 271.8801, тобто 54.3760 помножити на п'ять мінус три повних кола. Оскільки множення стискає коло, натальний аспект величиною 360 поділити на n стає з'єднанням у n-й гармоніці. Квінтилі по 72 градуси складаються в п'ятій, септилі по приблизно 51.4 градуса в сьомій, а дев'ята є західним відповідником навамші. Відповідь несе гармонічні планети, каркас домів і повну сітку аспектів, пораховану вже на гармонічних положеннях, тож карта придатна до вжитку одразу, без другого проходу.

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

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

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

| 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). |
| `harmonic` | number (2-36) | yes | The harmonic to compute. 5 for the quintile family, 7 for septiles, 9 for the navamsa analogue. |
| `houseSystem` | string | no | House system code, P for Placidus by default. |

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

```bash
curl -X POST https://api.astroway.info/v1/harmonics \
  -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,
  "houseSystem": "P",
  "harmonic": 5
}'
```

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

```json
{
  "ok": true,
  "data": {
    "harmonicNumber": 5,
    "planets": [
      {
        "id": 0,
        "name": "Sun",
        "longitude": 271.8801,
        "isRetrograde": false
      }
    ],
    "houses": { "system": "P", "cusps": [] },
    "aspects": []
  }
}
```

## Нотатки

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

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

- https://api.astroway.info/astrology-api/natal-chart/
- https://api.astroway.info/astrology-api/midpoint-tree/
- https://api.astroway.info/astrology-api/declinations/

---

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