Геокодер и поиск адресов

Методы и права

API принимает JSON с Bearer-ключом. Полный пример запроса. В SDK доступны методы geo.geocoder; их сигнатуры — в справочнике SDK.

Покрытие и обновление данных

Адресный поиск основан на OpenStreetMap. Наличие карты населённого пункта не гарантирует полноту адресов в геокодере: здания, номера домов и дороги могут отсутствовать или устареть. Перед интеграцией проверьте адреса, с которыми работает Ваш сервис, на бесплатной квоте API.

Версию и установленное покрытие адресной базы возвращает GET /v1/status с серверным ключом и правом status. Карта и геокодер обновляются отдельно. Дата сборки карты в публичном каталоге не является датой обновления геокодера.

Поиск по тексту

Тело запроса для search или geocode:

{"q":"Примерная улица","limit":5}

q — непустая строка до 256 символов, limit — от 1 до 10. Для ограничения области поиска используйте filters по схеме запроса. Не передавайте отсутствующие фильтры как массив [].

bias задаёт мягкий приоритет: обязательный focus с latitude/longitude и необязательный viewport с west, south, east, north. Все координаты конечные, центр находится внутри области, south <= north. При west > east область пересекает 180-й меридиан. Явные фильтры и распознанный город из текста сохраняют приоритет.

search_context в ответе показывает источник области (filters, query, viewport, none), locality или null и признак расширения expanded. Это приоритет поиска, а не местоположение пользователя. При повторе операции сохраняйте исходный bias; сознательный поиск в другой области получает новый Idempotency-Key.

Обратный геокодинг

Тело запроса для reverse. Замените координаты в примере на нужную точку:

{"point":{"latitude":55.75,"longitude":37.61},"radius_m":1000,"limit":5}

В API координаты задаются полями latitude и longitude. Геокодер учитывает попадание в связанное с адресом здание и расстояние до ближайшего объекта. Исходная точка остаётся в query_point: не заменяйте её точкой найденного адреса.

Значения relation: inside_linked_building, on_linked_building_boundary, nearest_linked_geometry, nearest_address_point. Радиус применяется к объекту: адресная точка может оказаться дальше радиуса, если контур здания покрывает исходную точку.

Выбор результата

• label — текст для отображения.
• point — координата или null. Наличие адреса не гарантирует наличие координат.
• needs_confirmation — необходимость подтверждения пользователем.
• precision — детализация распознанного адреса; это не обещание точности входа в здание.
• alternative_points — альтернативные точки; выбор остаётся за пользователем.
• ref — ссылка на объект, содержащая id и dataset_version. Передавайте её целиком в resolve как {"ref": selectedRef}.

Если ref устарел, повторите поиск и предложите новый выбор. Не заменяйте выбранный объект автоматически поиском по его подписи.

Атрибуция OpenStreetMap

Поиск адресов, прямое и обратное геокодирование используют данные OpenStreetMap по ODbL 1.0. Если эти функции доступны пользователям Вашего приложения, при публичном использовании укажите OpenStreetMap и добавьте ссылку на сведения о лицензии.

Атрибуцию можно разместить один раз в общем футере приложения, без подписи под каждым полем адреса, подсказкой или отдельным результатом. Футер должен быть читаемым и видимым пользователям на страницах, где доступны поиск адресов или геокодирование. Например:

<footer>
  Данные адресов:
  <a href="https://www.openstreetmap.org/copyright">© участники OpenStreetMap</a>
</footer>

Упоминание OpenStreetMap только на сайте Ммаппс не заменяет атрибуцию в Вашем приложении. При отображении карты соблюдайте правила OSMF для интерактивных карт: указание источника подложки обычно размещают в углу карты или рядом с ней.

Это правило закреплено в пункте 9.4 пользовательского соглашения. Подробнее — в разъяснениях OSMF по геокодированию.

Контур здания

geometry присутствует в кандидате поиска и в результате resolve: null, если связанного контура нет, иначе содержит shape и сведения о геометрии. shape — GeoJSON Polygon или MultiPolygon, в том числе с отверстиями. В GeoJSON порядок координат — [longitude, latitude].

Контур можно отобразить без дополнительного запроса. Если используете Accept: application/geo+json, он находится в properties.compact_geo.geometry.shape; геометрия самого Feature описывает точку результата.

Результаты и ошибки

Пустой успешный ответ тоже учитывается как операция. resolve и status не имеют отдельной платы, но ограничены по частоте. Повторы и обработка ошибок.