Следите за использованием ключа, пока не упёрлись в лимит
Наблюдение за заголовками квоты по ходу работы показывает приближение к лимиту задолго до того, как запрос будет отклонён.
Три способа передать API-ключ (и почему это важно)
Не каждый инструмент, работающий с API, обрабатывает аутентификацию одинаково, поэтому API принимает ключ несколькими способами, а не заставляет всё проходить через заголовок с одним-единственным именем.
Заголовок X-API-Key
Это самый прямой вариант: отдельный заголовок, который не несёт ничего, кроме ключа.
GET /v1/forward?q=Baker+Street
X-API-Key: mg_live_examplekey123Authorization: Bearer
Некоторые HTTP-клиенты и API-шлюзы уже настроены добавлять bearer-токен к каждому исходящему запросу, и использование этого механизма избавляет от необходимости добавлять рядом второй заголовок, специфичный для API.
GET /v1/forward?q=Baker+Street
Authorization: Bearer mg_live_examplekey123Базовая аутентификация HTTP (Basic auth)
Старые инструменты и некоторые межсерверные интеграции, построенные под других провайдеров, ожидают учётные данные в виде HTTP Basic auth. Ключ передаётся как имя пользователя, а пароль остаётся пустым.
GET /v1/forward?q=Baker+Street
Authorization: Basic bWdfbGl2ZV9leGFtcGxla2V5MTIzOg==Параметр запроса для всего остального
Когда инструмент вообще не позволяет управлять заголовками, например при быстрой проверке в адресной строке браузера или в клиенте, который поддерживает только настройку через URL, ключ можно также передать параметром прямо в запросе.
GET /v1/forward?q=Baker+Street&key=mg_live_examplekey123Почему выбор важен на практике
Ключ, переданный параметром запроса, гораздо легче попадает в серверные логи, историю браузера и заголовки Referer, чем ключ, переданный в заголовке запроса, поэтому выбирайте способ с заголовком всякий раз, когда вызывающий код хоть как-то это позволяет. Все четыре способа работают одинаково со всеми эндпоинтами и всеми совместимыми хостами, так что переход между ними позже, скажем, при переносе скрипта из проверки в браузере в полноценную серверную интеграцию, никак не меняет то, как квота или баланс учитываются по ключу.
Использование с совместимыми хостами
Каждый из 17 совместимых хостов принимает учётные данные в том же стиле, что и исходный провайдер, поэтому скрипт, написанный под соглашения об аутентификации другого провайдера, как правило, продолжает работать после того, как вы направите его на соответствующий совместимый хост My Geocode, без переписывания способа передачи ключа. Список хостов и стиль учётных данных, который ожидает каждый из них, приведены на странице совместимости.
Ошибка, которой стоит избегать
Привычку проверять скрипт с ключом в параметре запроса и так и оставлять его в продакшене приобрести легко, ведь параметр запроса часто самый быстрый способ получить первый рабочий запрос. Перейдите на способ с заголовком, X-API-Key или Authorization, прежде чем скрипт приблизится к рабочему трафику или попадёт в общий репозиторий, ведь ключ, видимый в URL, гораздо вероятнее окажется там, где вы не планировали, например в логе прокси или в файле истории браузера на общем компьютере.
Разницы в стоимости нет
Ни один из этих способов не меняет того, как оплачивается запрос. Каждый запрос по ключу по-прежнему одинаково засчитывается в его 2 500 бесплатных запросов в день, а сверх этого списывается с предоплаченного баланса или идёт в счёт пакета Unlimited.
Выбор подходящего способа аутентификации в основном зависит от того, что уже поддерживает вызывающий инструмент, а не от производительности или стоимости. Все подробности есть в документации по аутентификации.