REST API обратного геокодинга
Два GET-эндпоинта с одинаковым входом — географической точкой. Первый возвращает ближайший адрес с расстоянием и уровнем точности, а по требованию добавляет соседние дома, административную принадлежность по границам и ориентиры вокруг. Второй — объекты-ориентиры в радиусе до десяти километров.
Тарифицируется только найденное: 400, 404 и 503 списаний не создают, а обогащение, не давшее данных, не оплачивается.
Быстрый старт
Подключение API обратного геокодинга за три шага
Изучите эндпоинты
В Swagger ниже доступны корневой эндпоинт с обогащениями
(includeNeighbors, includeAdmin,
includeNearby) и nearby с параметрами
lat, lon, radiusKm, size.
Протестируйте
Выполните GET /api/geocodereverse?lat=55.7558&lon=37.6173
— получите адрес, расстояние до объекта и уровень точности координаты.
Одна единица работы.
Интегрируйте
Подставляйте адрес по геопозиции, обогащайте треки и заявки,
добавляйте ориентиры в наряд выездной бригады. Сколько списано —
видно в поле billedUnits самого ответа.
Возможности API
Что делает API обратного геокодинга удобным для интеграции
REST + JSON
GET-запросы и ответы в JSON — без промежуточных слоёв и без SDK.
Адрес по точке
?lat=&lon= — ближайший адрес с разобранными полями.
Что рядом
nearby — объекты-ориентиры в радиусе до 10 км.
Расстояние
distanceKm — насколько объект далеко от запрошенной точки.
Уровень точности
precision и layer — чья это координата и что именно найдено.
Принадлежность по границам
adminAreas — образования, внутри полигонов которых лежит точка.
Swagger
Спецификация OpenAPI и примеры запросов прямо на этой странице.
Соседние дома
neighbors — когда точка стоит между двумя зданиями и выбор спорный.
Единицы работы
Базовый ответ стоит одну единицу. Каждое включённое обогащение добавляет ещё одну — за ним стоит отдельная работа, а не другое оформление того же ответа.
| Параметр запроса | Что добавляет в ответ | Цена | Когда включать |
|---|---|---|---|
| базовый запрос | address — ближайший адрес с расстоянием и уровнем точности |
1 единица | Всегда: это и есть ответ на вопрос «какой здесь адрес». |
includeNeighbors |
neighbors — следующие по близости дома |
+1 единица | Точка стоит между двумя зданиями или у торца длинного дома, и автоматический выбор спорный. |
includeAdmin |
adminAreas — образования, внутри границ которых лежит точка |
+1 единица | Нужно знать, какому району и региону принадлежит сама точка, а не ближайший дом. |
includeNearby |
nearby — ориентиры вокруг точки |
+1 единица | Нужны ориентиры в одном ответе с адресом — дешевле, чем отдельный запрос «что рядом». |
Резервируется худший случай — «все включённые обогащения сработали», — а
списывается то, что действительно отработало. Попросили адрес и ориентиры
вокруг, ориентиров в радиусе не нашлось — спишется одна единица, не две.
Сколько именно списано, видно в поле billedUnits самого ответа:
сверять счёт в личном кабинете не нужно.
Единица считается по цене базового сервиса. Поэтому ориентиры, полученные
обогащением обратного геокодинга, обходятся дешевле, чем тот же список
отдельным вызовом nearby. Это сознательная скидка за то, что
всё приходит одним ответом, а не ошибка в тарифах.
Две административные иерархии
В ответе их действительно две, и это не дублирование: они отвечают на разные вопросы
| Поле ответа | Отвечает на вопрос | Откуда берётся | Состав |
|---|---|---|---|
address.admin |
«В каком городе ЧИСЛИТСЯ найденный дом» | Выписка из государственного реестра адресов — там иерархия записана за каждым объектом его создателем. | region, county, locality, street |
adminAreas |
«Внутри каких границ ЛЕЖИТ сама точка» | Геометрический расчёт: попадание точки в полигон границы. Приходит только с параметром includeAdmin. |
Список от общего к частному: name, kind, level, certainty, placeId |
Для дома в городе оба ответа обычно совпадают. Для точки в поле — нет: ближайший адрес может числиться за деревней в соседнем районе, а сама точка лежать внутри границ другого. Это содержательное расхождение, а не ошибка, поэтому поля разные и склеивать их нельзя. Принадлежность точки считается геометрически именно ради этого случая: иначе точка унаследовала бы район ближайшей деревни за двадцать километров.
Иерархия в адресе приходит из государственного адресного реестра: это выписка, а не расчёт по карте. Если нужно работать с самим реестром — искать объекты, разбирать дерево административного деления, проверять коды, — для этого есть отдельный сервис.
Сервис ГАР/ФИАСТарификация по результату
Списание происходит только тогда, когда для точки действительно что-то нашлось
| Исход запроса | Код ответа | Списание |
|---|---|---|
| Адрес найден либо в радиусе нашлись объекты | 200 | Тарифицируется |
| Адрес найден, но запрошенное обогащение данных не дало | 200 | Только за то, что отработало |
| Координаты вне диапазона или радиус больше предельного | 400 | Бесплатно |
| Адрес для точки не найден | 404 | Бесплатно |
| Ближайший объект дальше пяти километров — адресом точки он не является | 404 | Бесплатно |
| Пустой список «что рядом» | 404 | Бесплатно |
| Сервис временно недоступен | 503 | Бесплатно |
Адрес по координатам и режим «что рядом» тарифицируются и лимитируются независимо друг от друга: это разные по объёму работы запросы. Обогащения отдельным тарифом не являются — они считаются единицами работы по цене базового запроса. Цены и бесплатные лимиты обоих режимов смотрите на странице тарифов.
Нужна помощь с интеграцией?
Используйте Swagger ниже и примеры параметров. Для теста подойдут Postman, Thunder Client или curl.
Swagger документация API
Откройте спецификацию OpenAPI, чтобы проверить запросы и ответы обратного геокодинга.
Почему выбирают наш API
Преимущества REST API обратного геокодинга
Простая интеграция
Два понятных GET-эндпоинта с одинаковым входом. Подключается любым HTTP-клиентом, никакого SDK ставить не нужно.
Честная тарификация
Ненайденный адрес, слишком далёкий объект, пустой список и сбой на нашей стороне не создают списаний. Счёт предсказуем.
Границы данных видны в ответе
Уровень точности координаты, расстояние до объекта, число списанных единиц и оговорка о полноте данных по ориентирам приходят полями, а не остаются в документации, которую прочтут не все.
Понятное покрытие
Данные загружены по территории России. Мы говорим это до интеграции, а не после: точка за границей страны честно вернёт «не найдено» и не потратит ваш бюджет.
attribution в каждом ответе и обязана
отображаться там, где вы показываете полученные данные, — этого требует лицензия.
Источников два: написание адреса и его иерархия — из государственного реестра,
координата и ориентиры — из открытой карты.
Готовы подключить обратный геокодинг?
Встройте API в трекинг, логистику и аналитику или откройте веб-интерфейс, чтобы проверить пару координат руками.