# API інтерпретацій астрокартографії

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

## Ендпоінт

`POST /v1/acg/by-category`

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

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

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

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

Використовуйте це, коли ваш продукт відповідає на питання, сформульоване звичайною мовою: куди їхати заради роботи, яке з цих трьох міст краще для стосунків, що насправді означає ця лінія над моїм містом. Три форми покривають більшість збірок. Ранжування: надсилайте категорію й точку для кожного міста-кандидата та сортуйте за силою. Пояснення: викликайте /v1/acg/line-report для однієї планети й кута, щоб отримати повний текст плюс усі інші сфери життя, яких торкається ця лінія. Відкриття: заберіть GET /v1/acg/categories один раз за нуль кредитів і побудуйте інтерфейс із поверненої таксономії, щоб нова категорія з'являлася без релізу клієнта. Оскільки текст кураторський, а не згенерований, відповіді детерміновані, не посилаються на модель і не коштують нічого додатково в інференсі: той самий запит завтра поверне ті самі слова.

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

| 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. |
| `longitude` | number | yes | Birth-place longitude, decimal degrees. |
| `category` | string | yes | One of 19 life areas: career, love, money, health, home, learning, power, travel and more. Fetch the full list from GET /v1/acg/categories. |
| `point` | { lat, lng } | no | Optional geographic focus. With it, only lines running within radiusDeg of that point are returned and strength folds in proximity. |
| `radiusDeg` | number | no | Search radius in degrees around point. Default 4, range 0.5 to 20. |
| `polarity` | string | no | supportive, challenging, or all (default). Challenging lines are returned by default rather than hidden. |
| `includeText` | boolean | no | Attach the interpretation text for each line. Default true. |
| `includeCoordinates` | boolean | no | Attach the line geometry as `segments`, an array of `[lat, lng]` polylines. A rising or setting curve is several disjoint segments, so they are kept separate rather than concatenated. Default true; set false for a compact ranking response. |
| `language` | string | no | Interpretation language. Falls back to English then Ukrainian when a translation is missing, and the served language is reported per line. |

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

```bash
curl -X POST https://api.astroway.info/v1/acg/by-category \
  -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,
  "category": "career",
  "point": { "lat": 51.5074, "lng": -0.1278 },
  "radiusDeg": 8,
  "language": "en"
}'
```

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

```json
{
  "ok": true,
  "data": {
    "category": { "id": "career", "name": "Career" },
    "language": "en",
    "count": 3,
    "lines": [
      {
        "planet": "Jupiter",
        "type": "MC",
        "weight": 3,
        "polarity": "supportive",
        "strength": 2.31,
        "distanceDeg": 1.84,
        "pointCount": 341,
        "segments": [
          [[-85, 110.48], [-84.5, 110.48], "…"]
        ],
        "interpretation": {
          "title": "Jupiter - MC",
          "text": "Expansion of professional opportunity…",
          "lang": "en"
        }
      }
    ]
  }
}
```

## Нотатки

Таксономія покриває десять традиційних тіл. Хірон, Ліліт і місячні вузли присутні в геометрії /v1/acg, але свідомо лишені поза зіставленням, бо техніка у визначенні Джима Льюїса не надає їм кутового керування сферами життя. Ваги й полярності це редакційне судження, виражене як дані, версіоноване в репозиторії та придатне до аудиту, а не сховане всередині промпта. Текст інтерпретації це запит до бази знань, а не виклик мовної моделі, тож він стабільний, відтворюваний офлайн і вільний від застережень, яких вимагає згенерована інтерпретація.

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

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

---

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