Совместимость drop-in

Чтобы пользоваться этим API, изучать его не обязательно. Для семнадцати других API геокодирования и определения IP у нас работает хост, который принимает формат запросов провайдера и отвечает в формате ответов этого провайдера, отдавая наши данные. То же касается JavaScript-библиотек карт, которые выпускают эти провайдеры. Миграция сводится к смене имени хоста.

Как это работает

Каждый совместимый хост полностью реализует публичный HTTP-интерфейс одного провайдера: те же пути, те же параметры запроса, те же имена полей JSON, вложенность и типы, тот же набор статусов и тот же формат ошибок. Значения наши. Ваш клиентский код, код разбора ответов и обработка ошибок не меняются.

1. Смените хост. maps.googleapis.com меняется на gapi.mygeocode.com, dev.virtualearth.net на bing.mygeocode.com и так далее. Все пары приведены в таблице ниже.
2. Замените ключ или уберите его. Укажите свой ключ My Geocode в том параметре, где был старый ключ (key, apiKey, access_token, token...). Любой адрес получает 2 500 бесплатных запросов в день без ключа, а каждый ключ получает собственные 2 500, поэтому миграция и тестирование ничего не стоят.
3. Сравните. Прогоните выборку реальных запросов через оба хоста. Координаты будут немного отличаться, потому что данные разные; имена полей не будут.

$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"

$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

Все совместимые хосты

Все хосты работают на той же инфраструктуре, с теми же данными, той же бесплатной квотой и теми же ценами, что и api.mygeocode.com. Нажмите на провайдера, чтобы увидеть список его эндпоинтов, пример ответа и известные отличия.

Картографические библиотеки JavaScript

Смена провайдера больнее всего даётся в браузере, где карта, виджет геокодера и биллинг переплетены между собой. Для библиотек ниже сама библиотека загружается с нашего хоста (или, в случае MapLibre, Mapbox GL и Leaflet, направляется на наш хост через конфигурацию) и сохраняет свой публичный API: google.maps.Map, Microsoft.Maps.Map, H.Map и остальное. Тайлы, геокодирование, автодополнение и высоты предоставляем мы. Загрузки карты и тайлы бесплатны; вызовы геокодирования засчитываются как обычно.

На странице совместимых JavaScript-библиотек есть фрагменты кода «до» и «после», список того, что входит и не входит в каждую библиотеку, а также URL тайлов и стилей.

Куда передаётся ключ

Каждый хост принимает ключ там, где его ожидает исходный провайдер, а также в заголовке X-API-Key. Ключ необязателен: для 2 500 запросов в день с одного адреса он не нужен. Бесплатный ключ можно получить за минуту, и он добавляет баланс, пакеты и историю использования. Ключ с оплатой по мере использования можно использовать с двух IP-адресов за скользящие 24 часа, а ключ Unlimited с трёх; для большего числа адресов используйте больше ключей или пакетов (см. аутентификацию).

Квоты и ошибки на совместимых хостах

Дневная квота такая же, как и везде, и считается на ключ или на адрес, если ключ не передан, суммарно по api.mygeocode.com и всем совместимым хостам: 2 500 бесплатных запросов в день, затем баланс или ключ Unlimited. Заголовки X-Quota-* и X-Key-IPs-* отправляются на каждом хосте, поэтому реальное состояние можно узнать из заголовков при любом формате тела ответа. В теле ответа лимиты сообщаются так, как их сообщает провайдер:

Что совпадает, а что нет

Чек-лист миграции

1. Найдите имя хоста провайдера в своём коде и конфигурации. Часто оно встречается в нескольких местах: серверный код, мобильные приложения, правило CDN, закешированная конфигурация.
2. Замените его на совместимый хост из таблицы выше. Путь оставьте прежним.
3. Замените ключ на ключ My Geocode. Используйте по одному ключу на сервер или не больше двух; ключ с оплатой по мере использования принимает два IP-адреса за скользящие 24 часа, ключ Unlimited три.
4. Запустите свой существующий набор тестов. Он должен пройти без изменений. Если нужного вам поля нет, проверьте известные пробелы на странице хоста и сообщите нам.
5. Повторите несколько сотен реальных запросов на обоих хостах и сравните координаты и поля, которые вы показываете. Обратите внимание на precision там, где совместимый хост его отдаёт (как location_type, accuracy, resultType и так далее).
6. Понаблюдайте за X-Quota-Used в течение дня, чтобы подобрать тариф: баланс, если меньше примерно 19 000 запросов в день, ключ Unlimited, если больше.
7. Отмените старую оплату.

SDK провайдеров

Большинство официальных клиентских библиотек принимают собственный базовый URL, поэтому они тоже работают с совместимыми хостами: клиенты Google Maps Services (googlemaps для Python, @googlemaps/google-maps-services-js), SDK Mapbox (опция origin), REST-клиенты HERE, библиотеки ipinfo и обёртки для Nominatim, такие как geopy (domain=). Направьте их на хост из таблицы и передайте свой ключ My Geocode там, где был ключ провайдера.

Провайдера нет в списке

Добавление хоста занимает несколько дней работы, если формат провайдера документирован. Если вы пользуетесь сервисом, которого здесь нет, сообщите, каким именно, и примерно сколько запросов в день вы отправляете. Все недавно добавленные хосты появились по запросам пользователей.