# Gexarus API адресов Подключите «API адресов», кошелёк и суточный лимит в https://gexarus.com/my-services. Выдайте API-ключу разрешение на эту услугу. Актуальные цены и версия тарифа — в кабинете. OpenAPI: https://geo.gexarus.com/v1/openapi.json ## Запрос POST https://geo.gexarus.com/v1/addresses/suggest Authorization: Bearer Idempotency-Key: <уникальные 16–80 букв ASCII, цифр, _ или -> Content-Type: application/json {"query":"Москва","count":5} Для лицензии и ключа, ограниченного проектом, также передайте заголовок: X-Gexarus-Project: <точный UUID проекта> Без заголовка проекта обычный ключ использует подключение услуги к аккаунту. Секретные ключи предназначены для серверных вызовов. Не помещайте их в JavaScript сайта. Браузерные запросы с Origin отклоняются; вызывайте API через свой backend. ## Операции POST /v1/addresses/suggest — подсказки; query, count, locations и другие параметры по OpenAPI. POST /v1/addresses/reverse — адрес по координатам: {"lat":55.75,"lon":37.62}. POST /v1/addresses/lookup — поиск по коду ФИАС/ГАР или КЛАДР: {"query":"<код>"}. POST /v1/addresses/standardize — обработка одного адреса: {"query":"Москва, улица ..."}. GET /v1/addresses/results/ — бесплатное чтение ранее сохранённого результата. Ответ POST: request_id, operation_id, data:[{id,value,data}], usage.requests. ID результата — наш сохранённый снимок, а не код ФИАС. Чтение не обновляет его у поставщика. Для чтения нужны тот же аккаунт или доступ к текущему владельцу проекта. После передачи проекта результаты доступны новому владельцу, прежние расходы остаются прежнему. Новый владелец отдельно подключает оплату для новых запросов. ## Что оплачивается Один успешно выполненный запрос — одна единица независимо от числа подсказок. Корректный пустой результат тоже оплачивается. Стандартизация принимает один адрес за запрос. Проверка параметров, техническая ошибка, таймаут и чтение сохранённого ID не оплачиваются. Доступный баланс резервируется заранее; фактическое потребление списывается пакетами. Неиспользованный резерв возвращается. Бесплатное чтение работает и при приостановленной оплате. ## Повторы и ошибки При потере ответа повторите ТО ЖЕ тело с ТЕМ ЖЕ Idempotency-Key. Повтор не вызывает поставщика заново и не создаёт второе списание. Ответ хранится для повторов 24 часа; затем возвращается409. Сохранённые ID остаются доступны. Тот же ключ с другим телом —409. Для нового поиска создайте новый ключ. Ошибки: {"error":{"code":"..."}}. 401/403 — доступ;402 — согласие, баланс или суточный лимит;415/422 — параметры; 429 — ограничение частоты;502 — ошибка поставщика;504 — исход у поставщика неизвестен. При504 деньги клиента не списываются. Не повторяйте автоматически с новым ключом. ## Переход старых вызовов и виджета У старых маршрутов /api/Address/suggest, search, geolocate и data есть режим общего биллинга. Включите услугу для нужного аккаунта или проекта в кабинете. Сервер отправляет X-Gexarus-Address-Key и при необходимости X-Gexarus-Project. Для поиска используйте POST, JSON или form data, и тот же Idempotency-Key при повторе. Параметр gx_address_billing=1 защищает от потери заголовка промежуточным прокси. Ответ в оплачиваемом режиме содержит X-Gexarus-Address-Billing: active. Для geolocate в этом режиме передаются lat и lon. Форма прежних ответов сохраняется. Новый результат имеет ID длиной32 символа. Проверьте размер поля проекта до переключения. Получайте новые ID через /api/Address/data с тем же ключом и областью или GET /v1/addresses/results/. Чтение бесплатно. Исторические ID читайте через прежний /api/Address/data без заголовка биллинга. При подключении загрузите /cdn/address/script.js?v=address-billing-1. Старый URL долго кешируется. Виджет использует backend текущего сайта при вызове GxGeo.address(selector, {billingEndpoint: "/your-address-handler", billingCsrfToken: csrf}). Это маршрут вашего приложения. Он принимает POST JSON {operation,input} и Idempotency-Key. Операции suggest, geolocate и data. Backend берёт ключ и UUID из закрытой конфигурации и проверяет доступ пользователя, CSRF и лимит до отправки запроса. Штатный PHP-адаптер widget-backend.php вызывает старые маршруты в режиме общего биллинга. Передайте его функции dispatch разобранное тело, Idempotency-Key, обязательную функцию проверки доступа, URL geo, ключ и UUID. Верните полученные HTTP статус и JSON с Cache-Control: no-store. Ограничьте исходное тело32 КиБ и разрешите POST. Не передавайте в браузер серверный ключ. Уже сохранённый ID виджет читает бесплатно при открытии деталей. Вызовы без подключения биллинга продолжают работать по прежнему контракту.