PositionStack обычно встречается в более лёгких интеграциях, часто это один сервисный класс, оборачивающий один вызов API внутри более крупного приложения. Такая интеграция достаточно мала, чтобы её легко было упустить из виду, и ровно настолько велика, чтобы её было неприятно переписывать. Наш совместимый хост нацелен на то, чтобы полностью избавить от такого переписывания.
Хост в точности воспроизводит параметры запросов и тело ответа PositionStack, за исключением текста об авторских правах, условиях и конфиденциальности, который принадлежит нам, а не исходному провайдеру. Запрос, сформированный для эндпоинта геокодирования PositionStack, можно отправить на наш хост без изменений, а ответ возвращается в той же структуре, в которой его уже разбирает существующий код.
Меняются имя хоста и ключ. Этот ключ проходит аутентификацию тем из четырёх наших стандартных способов, который уже использует ваша интеграция: заголовок X-API-Key, заголовок Authorization: Bearer, HTTP Basic auth с ключом в качестве имени пользователя или параметр запроса.
Один сервисный класс вокруг одного вызова также относится к тем интеграциям, по которым никто не ведёт документацию, поэтому вопросы обычно всплывают позже в виде обращений в поддержку от того, кому достался этот код. Очередь поддержки My Geocode хранит готовые ответы именно на такие повторяющиеся вопросы о совместимости: значения заголовков, форматы ключей, что меняется и что нет, поэтому на простой вопрос о миграции отвечают быстро, и ему не приходится ждать за более сложными.
Проверить структуру ответа, не трогая код, тоже просто: интерактивная демонстрация на /demo/ может отправить пример запроса на любой эндпоинт или совместимый хост и показать, какие именно поля возвращаются. Часто этого достаточно, чтобы убедиться, что запрос в формате PositionStack будет корректно разобран дальше по цепочке.
Цены не зависят от того, какой совместимый хост обработал запрос. Любой адрес получает 2 500 бесплатных запросов в день вообще без ключа, с подсчётом по сети. Ключ добавляет ещё свои 2 500 бесплатных запросов в день. Сверх обеих квот предоплаченный баланс стоит 0,0001 € за запрос, или пакет Unlimited покрывает использование за 50 € в месяц, в точности как на всех остальных эндпоинтах и хостах платформы.
Каждый ответ также содержит наши заголовки квот: 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, что даёт прозрачность использования, которую обычная интеграция с PositionStack иначе не предоставила бы.
Для всего, что выходит за рамки стандартных полей совместимого ответа, mg_extras=1 в запросе или заголовок X-MG-Extras добавляет поверх необязательные дополнения, исключительно по вашему выбору и по умолчанию выключенные.
Хост описан на /compatibility/positionstack/, а более широкий обзор того, как работают все семнадцать совместимых хостов, находится на /docs/compatibility/. Если PositionStack спрятан в каком-нибудь сервисе вашего стека, перенаправить его сюда будет небольшим и обратимым изменением для проверки.