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