# Пошук місць

Три запити для поля "місце народження": від назви до координат і часового поясу, від координат до найближчого населеного пункту, від точки й дати до зсуву, який тоді показував годинник. Усі три відповідають з географічної бази GeoNames і бази часових поясів IANA.

## Пошук за назвою

```http
GET /v1/geo/search?q=Kiev&lang=uk&limit=5 HTTP/1.1
X-Api-Key: aw_live_...
```

- `q`: обов'язковий, назва або її початок будь-якою з наших мов і абеток. Регістр, діакритика й розділові знаки не важать: `krakow` знаходить Kraków, `St. Petersburg` знаходить Saint Petersburg, `Kiev` і `Київ` знаходять Київ.
- Текст після першої коми звужує пошук за регіоном або країною, а не порівнюється з назвою: `Springfield, Illinois`, `Springfield, MA`, `Paris, US`.
- `lang`: необов'язковий, одна з 21 мови сайту. Називає місце, регіон і країну цією мовою, якщо в даних така назва є. Порівняння охоплює всі мови незалежно від `lang`.
- `limit`: від 1 до 50, типово 10.
- `country`: необов'язковий, коди ISO 3166-1 alpha-2 через кому, до 20: `country=UA,PL`.

```json
{
  "query": "Kiev",
  "lang": "uk",
  "count": 1,
  "results": [
    {
      "id": 703448,
      "name": "Київ",
      "originalName": "Kyiv",
      "admin1": "Місто Київ",
      "admin1Code": "12",
      "countryCode": "UA",
      "country": "Україна",
      "latitude": 50.4547,
      "longitude": 30.5238,
      "timezone": "Europe/Kyiv",
      "population": 2952301,
      "featureCode": "PPLC",
      "matchedName": "Kiev",
      "exact": true
    }
  ],
  "note": "Populated places of 1000 people or more and administrative seats. A smaller place is absent, not misspelled.",
  "dataset": { "source": "GeoNames cities1000", "licence": "CC BY 4.0", "downloaded": "2026-11-07", "count": 171800 },
  "attribution": { "source": "GeoNames", "licence": "CC BY 4.0", "notice": "..." }
}
```

- `id` це ідентифікатор GeoNames: сталий, його можна зберігати.
- `originalName` з'являється лише тоді, коли `name` є перекладом.
- `matchedName` це форма, з якою збігся запит, наприклад давнє `Kiev`; `exact` каже, чи збіглася вся назва, чи лише її початок.
- `featureCode` це клас GeoNames: `PPLC` столиця, `PPLA` центр регіону першого рівня, `PPLX` частина міста.

Результати впорядковані за населенням, а збіг усієї назви важить удесятеро більше: неоднозначна назва на кшталт Springfield дає всі міста з цією назвою від найбільшого, а `kyi` ставить Київ вище за село Kyi.

`latitude`, `longitude` і `timezone` з результату передавайте просто в карту. `timezone` приймає назву поясу, а зсув на дату народження API визначить сам.

## Найближче місце до точки

```http
GET /v1/geo/reverse?lat=49.8397&lon=24.0297&lang=uk HTTP/1.1
X-Api-Key: aw_live_...
```

```json
{
  "latitude": 49.8397,
  "longitude": 24.0297,
  "timezone": "Europe/Kyiv",
  "nautical": false,
  "place": { "id": 702550, "name": "Львів", "countryCode": "UA", "timezone": "Europe/Kyiv", "featureCode": "PPLA", "distanceKm": 0.5 }
}
```

`timezone` це пояс самої точки, і біля кордону він може відрізнятися від поясу місця. Пошук іде за відстанню по великому колу й працює через 180-й меридіан і біля полюсів. У морі `nautical` дорівнює `true`, а пояс це морська годинна смуга, наприклад `Etc/GMT+2`, тобто UTC-2: знак у таких назвах за домовленістю обернений. `place.distanceKm` каже, як далеко суходіл.

## Зсув на дату

```http
GET /v1/geo/timezone?lat=50.45&lon=30.52&date=1990-05-15&time=15:30 HTTP/1.1
X-Api-Key: aw_live_...
```

```json
{ "timezone": "Europe/Kyiv", "date": "1990-05-15", "time": "15:30", "utcOffset": 4, "utcOffsetText": "+04:00", "standardOffset": 3, "isDst": true, "nautical": false }
```

Зсув береться з бази часових поясів на цю дату, а не з фіксованої таблиці: Київ відповідає +2 у січні, +3 у липні та +4 у травні 1990 року, коли тут діяв московський літній час. `date` типово сьогодні, `time` типово 12:00 і важить лише в день переведення годинника: пропущена година дає зсув до переведення, година, що була двічі, дає перший її прохід. До 1970 року база не скрізь надійна; якщо ви знаєте, що показував місцевий годинник, передайте в карту `timezoneOffset`.

## Без ключа, для віджетів

```http
GET /v1/public/geo/search?q=Kiev&lang=uk&limit=5 HTTP/1.1
```

Той самий пошук відповідає без ключа, для поля місця народження на публічній сторінці. Він рахується в публічний ліміт, 30 запитів на годину з адреси відвідувача, тож надсилайте запит, коли відвідувач зробив паузу в наборі, а не на кожну клавішу. Відповідь можна кешувати добу. Зворотний пошук і зсув на дату потребують ключа; для браузера візьміть публічний ключ (publishable), обмежений `geo/*`.

## Що охоплено

Близько 172 000 місць: кожен населений пункт від 1000 мешканців і центри адміністративних регіонів. Меншого села немає, а не написано з помилкою, тож запропонуйте найближче місто або дайте ввести координати вручну. Назви ті, що є в GeoNames нашими мовами; де мовою назви немає, повертається назва GeoNames.

## Атрибуція

Дані про місця з [GeoNames](https://www.geonames.org/) за ліцензією [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Якщо ви показуєте ці назви або координати своїм користувачам, зазначайте те саме авторство: воно приходить у кожній відповіді як `attribution`.

## Ціна

`/v1/geo/search`, `/v1/geo/reverse` і `/v1/geo/timezone` коштують по 5 кредитів.

Пошук без ключа кредитів не витрачає і має публічний ліміт.