Документация

Каждый вызов представляет собой GET-запрос к https://api.mygeocode.com/v1/ с параметрами в строке запроса, ответ приходит в JSON. На этой странице описано то, что общее для всех эндпоинтов. Параметры и поля каждого эндпоинта описаны на его отдельной странице.

Ваш первый запрос

Для первых 2 500 запросов в день с одного адреса ключ не нужен. С любого компьютера:

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

Этот запрос засчитан как 1 из 2 500 бесплатных запросов, которые ваш адрес получает сегодня. С ключом он был бы засчитан ключу, а заголовки дополнительно показали бы ваш баланс и данные по IP-слотам. Заголовки ответа показывают ваше текущее положение:

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

Переходите с другого провайдера?

Возможно, остальная часть этой страницы вам не понадобится. Если ваш код уже работает с Google Maps, Bing Maps, HERE, Mapbox, Geocode.Farm, Nominatim, OpenCage, LocationIQ, Geoapify, TomTom, MapQuest, Geocodio, PositionStack, ip-api, ipinfo, ipstack или Open-Elevation, у нас есть хост, который понимает формат запросов и ответов этого провайдера и отдаёт наши данные. Смените имя хоста, укажите свой ключ там, где был старый, и оставьте код разбора ответов как есть. То же касается Google Maps JavaScript API, Bing Maps V8, HERE Maps for JavaScript, MapQuest.js, а также плагинов геокодера для MapLibre, Mapbox GL и Leaflet.

• Google Maps
• Bing Maps
• HERE
• Mapbox
• Geocode.Farm
• Nominatim
• OpenCage
• LocationIQ
• Geoapify
• TomTom
• MapQuest
• Geocodio
• PositionStack
• ip-api
• ipinfo
• ipstack
• Open-Elevation
• Картографические библиотеки JavaScript

Как работают совместимые хосты: полная таблица хостов, соответствие ключей, соответствие ошибок и чек-лист миграции.

Базовый URL и эндпоинты

Обслуживается только HTTPS. Запросы по обычному HTTP отклоняются с кодом 400, а не перенаправляются, чтобы ключ никогда случайно не был отправлен открытым текстом. Поддерживаются HTTP/2 и HTTP/3. Ответы сжимаются, если клиент принимает gzip или br.

Обёртка ответа

Каждый ответ представляет собой JSON-объект с полем status со значением ok или error.

• При ok далее идут данные: results (массив) для эндпоинтов, которые могут вернуть несколько совпадений, result (объект или null) для обратного геокодирования и плоские поля для определения IP и часового пояса.
• При error в ответе есть объект error со строкой code, предложением message и, когда это уместно, параметром param, который вызвал ошибку. HTTP-статус соответствует ей. См. ошибки.

Корректный запрос, по которому ничего не найдено, возвращает ok с пустым массивом results или result, равным null. Это не ошибка, и такой запрос засчитывается.

Параметры, которые принимает каждый эндпоинт

Имена параметров чувствительны к регистру и пишутся строчными буквами. Неизвестные параметры игнорируются, а пустые считаются отсутствующими, поэтому HTML-форма может отправлять необязательные поля пустыми. Координаты задаются в десятичных градусах; lat от -90 до 90 и lon от -180 до 180. Текст передаётся в UTF-8 и должен быть закодирован для URL.

Аутентификация в одном абзаце

Ключ необязателен: каждый адрес получает 2 500 бесплатных запросов в день без него. Ключ передаётся в заголовке X-API-Key, в виде токена Authorization: Bearer или в параметре key; ключи бесплатны, а для аккаунта нужны ваше имя, адрес электронной почты и пароль. У каждого ключа есть собственные 2 500 бесплатных запросов в день; сверх этого запросы списываются с предоплаченного баланса аккаунта по 0,0001 € за запрос или бесплатны для ключа, входящего в пакет Unlimited (50 € в месяц). Запросы без ключа и запросы с ключом из одной и той же сети делят одну дневную квоту. Ключ с оплатой по мере использования работает с двух IP-адресов за скользящие 24 часа, ключ Unlimited с трёх. Полные правила описаны на странице аутентификации.

Заголовки квоты

Вызовы из браузера

CORS включён на каждом эндпоинте, и заголовки квоты доступны, но ключ в исходном коде страницы становится публичным и исчерпает свои IP-слоты после пары посетителей. Выполняйте вызовы со своего сервера; см. ключи и браузеры.

Версионирование

Префикс пути /v1/ и есть версия. В пределах версии мы добавляем поля и параметры, но никогда не удаляем и не переименовываем их и никогда не меняем смысл существующего поля. Если нам когда-нибудь понадобится что-то сломать, это попадёт в /v2/, а /v1/ продолжит работать не менее шести месяцев после объявления. О дополнениях мы сообщаем в разделе Новости блога.

Ваш JSON-парсер должен игнорировать неизвестные ему поля. Это единственное требование прямой совместимости.