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

Подсказки адресов, координаты по адресу и поиск адреса по точке.

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

| HTTP | Право ключа | Назначение |
| --- | --- | --- |
| `POST /v1/search` | `search` | Подсказки при вводе |
| `POST /v1/geocode` | `geocode` | Координаты по адресу |
| `POST /v1/reverse` | `reverse` | Адрес по координатам |
| `POST /v1/resolve` | `resolve` | Получить объект по выбранному `ref` |
| `GET /v1/status` | `status`, серверный ключ | Версия и покрытие данных |

API принимает JSON с Bearer-ключом. [Полный пример запроса](https://mmapps.ru/docs/getting-started). В SDK доступны методы `geo.geocoder`; их сигнатуры — в [справочнике SDK](https://mmapps.ru/docs/sdk).

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

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

Версию и установленное покрытие адресной базы возвращает `GET /v1/status` с серверным ключом и правом `status`. Карта и геокодер обновляются отдельно. Дата сборки карты в [публичном каталоге](https://cdn.mmapps.ru/catalog/channels/stable.json) не является датой обновления геокодера.

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

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

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

`q` — непустая строка до 256 символов, `limit` — от 1 до 10. Для ограничения области поиска используйте `filters` по [схеме запроса](https://mmapps.ru/gateway.openapi.yaml). Не передавайте отсутствующие фильтры как массив `[]`.

`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`. Замените координаты в примере на нужную точку:

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

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

| Поле | Как использовать |
| --- | --- |
| `relation` | Отношение точки к найденному объекту |
| `geometry_distance_m` | Расстояние до контура; `null`, если контура нет |
| `point_distance_m` | Расстояние до возвращённой адресной точки |
| `geometry.shape` | Контур здания, если он доступен |

Значения `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 и добавьте ссылку на сведения о лицензии.

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

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

Упоминание OpenStreetMap только на сайте Ммаппс не заменяет атрибуцию в Вашем приложении. При отображении карты соблюдайте [правила OSMF для интерактивных карт](https://osmfoundation.org/wiki/Licence/Attribution_Guidelines#Interactive_maps): указание источника подложки обычно размещают в углу карты или рядом с ней.

Это правило закреплено в [пункте 9.4 пользовательского соглашения](https://mmapps.ru/documents/terms#maps-licenses). Подробнее — в [разъяснениях OSMF по геокодированию](https://osmfoundation.org/wiki/Licence/Community_Guidelines/Geocoding_-_Guideline).

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

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

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

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

| `outcome` | Действие приложения |
| --- | --- |
| `candidates` | Показать варианты для выбора |
| `not_found` | Предложить уточнить адрес |
| `needs_context` | Уточнить город, улицу или другой контекст |
| `outside_coverage` | Сообщить, что точка вне покрытия |

Пустой успешный ответ тоже учитывается как операция. `resolve` и `status` не имеют отдельной платы, но ограничены по частоте. [Повторы и обработка ошибок](https://mmapps.ru/docs/billing).