Пошук місць

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

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

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.

{
  "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 визначить сам.

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

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

{
  "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 каже, як далеко суходіл.

Зсув на дату

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_...

{ "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.

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

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

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

Що охоплено

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

Атрибуція

Дані про місця з GeoNames за ліцензією CC BY 4.0. Якщо ви показуєте ці назви або координати своїм користувачам, зазначайте те саме авторство: воно приходить у кожній відповіді як attribution.

Ціна

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

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