Geocodio заработал репутацию на простом пакетном геокодировании, и немало построенных на нём интеграций сильно опираются на это пакетное поведение. Наш совместимый хост в точности повторяет структуру как одиночных, так и пакетных запросов, поэтому такая зависимость не становится препятствием для перехода.
Хост точно воспроизводит параметры запросов и тело ответа Geocodio, за исключением текста об авторских правах, условиях и конфиденциальности, который принадлежит My Geocode. Запросы, сейчас сформированные для эндпоинтов Geocodio, одиночные или пакетные, можно отправлять на наш хост как есть, а ответы разбираются так же, как уже ожидает существующий код.
Пакетные запросы здесь считаются так же, как и везде на платформе: каждый адрес внутри пакетного вызова считается одним запросом, а не весь вызов целиком. Это сохраняет точность учёта квот независимо от того, содержит ли вызов один адрес или много.
Пакет из пятисот адресов, отправленный одним вызовом, учитывается как пятьсот запросов в квоте, а если бесплатные лимиты уже исчерпаны, то и в предоплаченном балансе, точно так же, как пятьсот отдельных вызовов. Именно такая детализация позволяет X-Quota-Used и X-Credits-Remaining оставаться точными сразу после завершения большого пакета, а не выравниваться через несколько минут, когда какая-нибудь фоновая задача наверстает упущенное.
Аутентификация использует наши четыре стандартных варианта: заголовок X-API-Key, заголовок Authorization: Bearer, HTTP Basic auth с ключом в качестве имени пользователя или параметр запроса, в зависимости от того, что уже использует ваша текущая интеграция с Geocodio.
Цены одинаковы на всей платформе. Любой адрес получает 2 500 бесплатных запросов в день без всякого ключа, с подсчётом по сети. Ключ добавляет свои 2 500 бесплатных запросов в день. Сверх этого предоплаченный баланс расходуется по 0,0001 € за запрос, или пакет Unlimited покрывает всё за 50 € в месяц, и тот же тариф применяется как к одиночным запросам, так и к элементам пакета.
Купоны в личном кабинете часто используют, чтобы протестировать такую миграцию с большим количеством пакетных запросов, не выделяя сразу реальный бюджет: купон зачисляет баланс на аккаунт до того, как вы решите, пополнять ли его полноценно через предоплаченный баланс или пакет Unlimited.
Заголовки квот сопровождают каждый ответ, пакетный или одиночный: X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining, X-Quota-Network-Used и X-Credits-Remaining точно отражают, сколько элементов израсходовал пакет, и эту точность легко учитывать при планировании.
Если проекту нужно больше, чем стандартный совместимый ответ, mg_extras=1 в запросе или заголовок X-MG-Extras накладывает поверх необязательные дополнительные поля, не затрагивая базовую структуру, пока это явно не запрошено.
Хост описан на /compatibility/geocodio/, а общие рекомендации по переводу существующей интеграции находятся на /docs/compatibility/. Тестовый пакетный вызов к новому хосту позволяет быстро убедиться, что подсчёт квот работает именно так, как ожидается, прежде чем полагаться на него при реальных объёмах.