# API найкращих місць

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

## Ендпоінт

`POST /v1/acg/best-places`

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

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

Для кожного міста ендпоінт вимірює відстань до кожної лінії, яку називає обрана категорія, і зважує її за близькістю. Відстань рахується з часового кута й висоти світила, а не по намальованій полілінії, і тому вона точна: відстань до лінії сходу чи заходу дорівнює висоті світила в градусах дуги, бо зенітна відстань це і є відстань по великому колу від точки, над якою світило стоїть; а зсув меридіанної лінії це часовий кут у градусах довготи, тож відстань по землі дорівнює йому, помноженому на косинус широти. Вплив спадає лінійно до нуля на орбісі, за замовчуванням 1126 км, тобто 700 миль, які брав Джим Льюїс. Підтримувальний і напружений підсумки тримаються окремо, і кожна лінія повертається зі своєю відстанню, тож місце може бути сильним і водночас турбулентним, а не усередненим. Далі результати прорідж��ються так, щоб жодні два не були ближче 300 км, і кількість прибраних повідомляється.

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

Беріть тоді, коли користувач поставив очевидне наступне питання. Астрокартографія малює лінії, фільтр за категорією каже, які з них важать для грошей чи кохання, а це каже, куди власне їхати. Різниця між картою і відповіддю. У продукті результат лягає прямо в короткий список: кожне місце несе координати, населення, часовий пояс і точний перелік ліній, які його туди привели, з відстанями в кілометрах, тож міркування можна показати, а не проголосити. Місце народження не потрібне й не використовується, бо лінії належать моменту народження.

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

| 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. |
| `category` | string | yes | One of the 19 life categories. The list is at GET /v1/acg/categories. |
| `countries` | string[] (ISO 3166-1 alpha-2) | no | Restrict the search. GET /v1/acg/countries lists what can be ranked and how many cities each country has. |
| `minPopulation` | number | no | Floor on population. The bundled set starts at 15,000, so a lower value changes nothing. |
| `orbKm` | number | no | How far a line reaches. Default 1126, the 700 miles Jim Lewis used. |
| `minSeparationKm` | number | no | Keep results at least this far apart. Default 300. Set 0 for raw score order. |
| `limit` | number | no | How many places to return. Default 25, maximum 100. |
| `sort` | "net" | "supportive" | no | Ranking key. Net (default) subtracts the challenging total; supportive ignores it for ordering only, never for reporting. |

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

```bash
curl -X POST https://api.astroway.info/v1/acg/best-places \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "date": "1990-05-15",
  "time": "14:30:00",
  "timezoneOffset": 3,
  "category": "career",
  "limit": 10
}'
```

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

```json
{
  "ok": true,
  "data": {
    "type": "acg-best-places",
    "orbKm": 1126,
    "minSeparationKm": 300,
    "suppressedAsTooClose": 99,
    "maxPossibleSupportive": 12,
    "pool": { "citiesConsidered": 34028, "citiesWithAnyLine": 13589 },
    "places": [
      {
        "name": "Ålesund",
        "country": "Norway",
        "countryCode": "NO",
        "lat": 62.4723,
        "lon": 6.1549,
        "population": 46747,
        "supportive": 3.2529,
        "challenging": 0,
        "net": 3.2529,
        "supportivePercent": 27.1,
        "lines": [
          {
            "planetName": "Sun",
            "angle": "MC",
            "weight": 3,
            "polarity": "supportive",
            "distanceKm": 22,
            "contribution": 2.9414
          }
        ]
      }
    ],
    "attribution": {
      "source": "GeoNames",
      "licence": "CC BY 4.0",
      "licenceUrl": "https://creativecommons.org/licenses/by/4.0/"
    }
  }
}
```

## Нотатки

Проріджування тут не косметика. Астрокартографічна лінія це крива, тож кожен населений пункт уздовж неї має майже однаковий бал, і без рознесення перша десятка для кар'єри поверталася десятьма норвезькими містечками в межах 70 км, два з яких були районами третього. Поставте `minSeparationKm` у 0, щоб побачити сирий порядок. **Це не геокодування.** Список міст вбудований і починається з 15 000 мешканців: менше містечко відсутнє в ранжуванні, а не погано оцінене, і довільну назву місця розпізнати неможливо. Щоб оцінити власну конкретну точку, передайте її координати в ендпоінт зон астрокартографії. Назви міст, координати й населення взято з географічної бази GeoNames за ліцензією CC BY 4.0; показ цих даних тягне за собою те саме зазначення авторства, тому атрибуція їде в тілі кожної відповіді, а не лише тут.

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

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

---

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