Квоты, баланс и лимиты

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

Дневная квота

Квота с ключом считается на ключ, а не на аккаунт: три ключа означают трижды по 2 500 бесплатных запросов. Квота без ключа считается на адрес, и адреса из одной сети делят её между собой. Сеть и ключи, используемые из неё, расходуют одну квоту: запросы без ключа уменьшают то, что получит в этот день ключ, используемый из той же сети, и наоборот, поэтому бесплатные 2 500 нельзя получить дважды с одного места. Баланс относится к аккаунту, и с него списывает тот ключ, который превысил свою квоту. Сутки это календарные сутки UTC; X-Quota-Reset содержит точное время Unix следующего сброса.

Что считается запросом

• Каждый успешный вызов (200) любого эндпоинта засчитывается как один запрос, независимо от того, нашёл ли он что-нибудь.
• Каждый элемент пакетного вызова засчитывается как один запрос: каждый адрес в пакете IP, каждая точка в многоточечном вызове высот или часовых поясов, каждая запись на пакетных эндпоинтах совместимых хостов. Исходные провайдеры считают так же. Пакет, превышающий остаток квоты, отклоняется целиком до начала обработки с собственной ошибкой лимита провайдера, а не обрабатывается частично. Каждый хост принимает за вызов столько элементов, сколько и его исходный провайдер (100 для ip-api и MapQuest, 50 для ipstack, 512 для высот Google, 1 000 для ipinfo, Mapbox и Geoapify, 1 024 для Bing и Open-Elevation, 10 000 для Geocodio и асинхронного пакета TomTom; 100 на собственных эндпоинтах). Получение сохранённого асинхронного результата не засчитывается.
• Вызовы, отклонённые с кодом 400, 401, 402, 403 или 404, не засчитываются и ничего не стоят.
• Вызовы, завершившиеся ошибкой 500 или 503, не засчитываются и ничего не стоят.
• Тайлы карт, JSON стилей и загрузки библиотек из совместимых JavaScript-библиотек не засчитываются.

IP-слоты

Ключ работает с двух IP-адресов одновременно (с трёх для ключа Unlimited). Каждый адрес удерживает свой слот 24 часа с момента первого запроса, а затем освобождает его. Запрос с ещё одного адреса, когда все слоты заняты, получает 403 key_ip_limit с временем освобождения следующего слота. Подробности и примеры приведены на странице аутентификации.

Всплески

Фиксированного лимита запросов в секунду сейчас нет, ни с ключом, ни без него. Трафик, похожий на зациклившийся скрипт или атаку, может замедляться, и мы сообщим вам, если это произойдёт с одним из ваших ключей. Если у вас большая задача, используйте пакетные формы (ips, locations), а не тысячи одиночных вызовов.

Как читать заголовки

x-quota-limit: 2500          # free per day for this key; -1 on an Unlimited key
x-quota-used: 2431           # counted today on this key, including this request
x-quota-free-remaining: 69   # free requests left today on this key
x-credits-remaining: 148200  # requests the account's credit still covers
x-key-ips-used: 1            # IP slots currently held on this key
x-key-ips-limit: 2           # slots on this key
x-quota-reset: 1789948800    # Unix time of the next 00:00 UTC
x-request-id: 2726386e38428697

Обработка 402 и 403

{ "status": "error", "error": { "code": "no_credits", "message": "The free allowance of 2500 requests for today is used and the account balance (€0.0000, 0 requests) does not cover this request. Add credit at https://www.mygeocode.com/dashboard or wait for the reset at 00:00 UTC." } }

Не повторяйте запрос в цикле: ответ будет тем же, пока не пополнится баланс или не наступят новые сутки. Прочитайте X-Quota-Reset и либо подождите, либо завершите операцию с ошибкой и сообщите пользователю, либо пополните баланс. Личный кабинет присылает письмо, когда баланс подходит к концу.

{ "status": "error", "error": { "code": "key_ip_limit", "message": "This key is already in use from 2 IP addresses in the last 24 hours (limit 2). The next slot frees at 2026-09-21 23:06 UTC. Use another key or an additional Unlimited package for more addresses." } }

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

Как сократить число запросов

Результаты можно кешировать бессрочно, так и делайте. Адреса не перемещаются; то же прямое геокодирование завтра даст тот же ответ. Блоки IP меняются медленно; сутки являются безопасным временем кеширования. Правила часовых поясов для точки меняются редко, а имя IANA практически никогда. Для автодополнения применяйте debounce к вводу примерно на 150 мс и прекращайте отправку, как только пользователь выбрал подсказку.