Аутентификация

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

Без ключа

Отправьте запрос вообще без учётных данных, и он будет обработан. Каждый адрес получает так 2 500 запросов в день, отсчёт ведётся с 00:00 UTC по всем эндпоинтам и всем совместимым хостам, с теми же данными и теми же ответами, что и у платного аккаунта. Сверх этого API отвечает 429 quota_exceeded с заголовком Retry-After до сброса; ничего не списывается и ничего не ставится в очередь.

Важно знать две вещи. Адреса, принадлежащие одной сети, делят одну квоту, поэтому загруженный офис, кампус или один облачный регион могут исчерпать её быстрее, чем отдельная машина. Кроме того, сеть и ключи, используемые из неё, расходуют одну и ту же квоту: запросы без ключа уменьшают то, что сегодня получит ключ, используемый из этой сети, а бесплатные запросы с этим ключом уменьшают то, что сеть получит без ключа. Поэтому регистрация добавляет баланс, пакеты и историю, но не вторые бесплатные 2 500 с того же места.

Как получить ключ

Зарегистрируйтесь на www.mygeocode.com/signup, указав имя, адрес электронной почты и пароль. Ваш первый ключ показывается один раз, сразу же; скопируйте его, потому что хранится только его хеш. Создавайте сколько угодно дополнительных ключей в разделе API-ключей, давайте каждому метку (по одному на сервер или приложение, это хорошая привычка) и отзывайте любой из них в любой момент.

Каждый ключ получает 2 500 бесплатных запросов в день, отсчёт ведётся с 00:00 UTC по всем эндпоинтам и всем совместимым хостам. Сверх этого запросы списываются с предоплаченного баланса аккаунта по 0,0001 € за запрос, если только ключ не входит в пакет Unlimited.

Как передать ключ

Любой из этих способов работает на каждом хосте. Предпочитайте заголовок: строки запроса попадают в логи серверов, историю браузеров и прокси.

$ curl -H "X-API-Key: mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl -H "Authorization: Bearer mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_7f3c2a19e04b...d1"

$ curl -u "mg_7f3c2a19e04b...d1:" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

На совместимых хостах ключ также передаётся туда же, куда передавался ключ исходного провайдера: key для Google, Bing, Geocode.Farm, OpenCage, LocationIQ, TomTom и MapQuest; apiKey для HERE и Geoapify; access_token для Mapbox; api_key для Geocodio; access_key для PositionStack и ipstack; token для ipinfo. Клиенты Nominatim и Open-Elevation добавляют key= или заголовок, поскольку у этих двух сервисов нет собственного ключа.

Помимо параметра запроса, на каждом хосте принимаются четыре способа передачи учётных данных, поэтому клиентская библиотека, которая аутентифицируется по правилам провайдера, не требует изменений: заголовок X-API-Key, Authorization: Bearer, базовая HTTP-аутентификация с ключом в качестве имени пользователя (это отправляет curl -u KEY: и это используют примеры ipinfo) и заголовок X-Goog-Api-Key, который отправляют клиенты Google. Ключ в теле формы тоже считывается для эндпоинтов, принимающих POST. Смена имени хоста и ключа и есть вся миграция.

Два вида ключей

IP-слоты

Ключ можно одновременно использовать с ограниченного числа IP-адресов: с двух для ключа с оплатой по мере использования и с трёх для ключа Unlimited. Правило скользящее и действует для каждого адреса отдельно:

• Когда адрес впервые использует ключ, он занимает слот и удерживает его 24 часа с момента этого первого запроса.
• Когда эти 24 часа истекают, слот освобождается сам, независимо от того, что делают другие адреса. Если тот же адрес вернётся позже, он просто снова займёт слот.
• Запрос с нового адреса, когда все слоты заняты, отклоняется с кодом 403 и кодом ошибки key_ip_limit. В сообщении указано, когда освободится следующий слот. Отклонённые запросы не засчитываются.

Например, если два сервера впервые использовали ключ в 02:00, а третий в 04:00, то два слота освободятся в 02:00 следующего дня, а третий в 04:00. В личном кабинете видно, какие адреса занимают слоты ключа и когда освободится каждый. Нужно больше машин? Создайте больше ключей с оплатой по мере использования или добавьте пакеты Unlimited; каждый пакет приносит собственный ключ.

Это ограничение существует, потому что ключи утекают. С ним ключ, оказавшийся в публичном репозитории, почти ничего не стоит для того, кто его нашёл, а поскольку баланс предоплачен, никто не сможет потратить больше, чем вы внесли.

Ключи и браузеры

Не размещайте ключ в JavaScript или в мобильном приложении. Любой может извлечь его со страницы, а каждый посетитель это новый IP-адрес, поэтому слоты ключа закончатся после второго или третьего посетителя. Вызывайте API со своего сервера и храните ключ там. Совместимые JavaScript-библиотеки карт загружают тайлы и библиотеки без ключа; через ваш сервер должны идти только их вызовы геокодирования.

Отзыв и ротация

Отзовите ключ в личном кабинете, и он перестанет работать в течение минуты. Сначала создайте новый ключ, разверните его, затем отзовите старый; в промежутке работают оба. Сами по себе ключи никогда не истекают.

Отказы

Ни один из этих отказов не засчитывается в квоту и не списывает баланс. На совместимых хостах они возвращаются в формате исходного провайдера; см. совместимость.