API Геокодера Яндекс Карт: Искать адрес только в своём городе

Сценарий из mcp-everything. Актуально на 2026-10-24.

Подсказки и проверка адреса доставки в зоне работы: чтобы «Ленина, 5» нашлось в твоём городе, а не в соседнем.

1. Задай область поиска: bbox — углами «долгота1,широта1~долгота2,широта2», или ll (центр) и spn (протяжённость).
2. Передай rspn = 1, чтобы искать только внутри области; с rspn = 0 область лишь повышает приоритет результатов.
3. Запроси несколько вариантов: GET /v1 с results до 50 и покажи их пользователю на выбор. Следующие страницы — через skip (кратно results).
4. Если в geocode переданы координаты, ограничение области не применяется.

curl -G https://geocode-maps.yandex.ru/v1/ \
  -d apikey=<ключ> --data-urlencode 'geocode=Ленина 5' \
  -d bbox=49.0,55.7~49.3,55.9 -d rspn=1 -d results=5 -d lang=ru_RU -d format=json

Базовые URL

• Боевой: https://geocode-maps.yandex.ru

Авторизация

Тип: API-ключ

Ключ из Кабинета разработчика передаётся в параметре apikey; активируется в течение 15 минут после получения. Для защиты ключа от кражи можно подписывать запросы параметром signature.

https://geocode-maps.yandex.ru/v1/?apikey=YOUR_API_KEY&geocode=бульвар+Мухаммед+Бин+Рашид+1&format=json

Методы сценария

GET /v1 — Геокодирование

Пример обратного геокодирования:

Постраничная выдача (объекты с 11-го по 15-й):

Структура ответа (сокращена):

Параметр	Где	Тип	Обяз.	Описание
apikey	query	string	да	Ключ из Кабинета разработчика
geocode	query	string	да	Адрес (прямое геокодирование) или координаты (обратное)
lang	query	string	да	Язык ответа language_region: ru_RU, uk_UA, be_BY, en_RU, en_US, tr_TR
sco	query	string	нет	Порядок координат в geocode: longlat (по умолчанию) или latlong
kind	query	string	нет	Вид топонима при обратном геокодировании: house, street, metro, district, locality
rspn	query	boolean	нет	Ограничить поиск областью ll/spn или bbox: 0 — нет (по умолчанию), 1 — да
ll	query	string	нет	Долгота и широта центра области поиска
spn	query	string	нет	Протяжённость области поиска по долготе и широте
bbox	query	string	нет	Область поиска углами x1,y1~x2,y2; приоритетнее ll+spn
format	query	string	нет	Формат ответа: json
results	query	integer	нет	Максимум объектов, по умолчанию 10, не больше 50
skip	query	integer	нет	Сколько объектов пропустить; должно делиться на results
uri	query	string	нет	ID объекта для получения доп. информации, вместо текста и координат
signature	query	string	нет	Подпись запроса

Пример запроса:

https://geocode-maps.yandex.ru/v1/?apikey=YOUR_API_KEY&geocode=55.270141,25.193445&format=json

Пример ответа:

https://geocode-maps.yandex.ru/v1/?apikey=YOUR_API_KEY&geocode=Дубай+Марина&results=5&skip=10&format=json

Нюансы

• Координаты в ответе (Point.pos, boundedBy.Envelope) — в порядке «долгота широта», через пробел.
• GeocoderMetaData.precision показывает точность совпадения номера дома: exact, number, near, range, street, other.
• Address.Components[] — компоненты адреса парами kind/name от крупного к мелкому; поле AddressDetails устарело.
• GeocoderResponseMetaData.fix и suggest — исправление опечаток в запросе.
• Ограничение области (rspn, ll, spn, bbox) игнорируется, если в geocode переданы координаты.
• HTTP-метод в документации отдельно не указан — запрос задаётся URL с параметрами.

Другие сценарии

• Получить координаты по адресу
• Определить адрес по координатам

---

Если этого недостаточно — официальная документация: https://yandex.ru/maps-api/docs/geocoder-api/index.html Вся интеграция одним документом: https://mcp-everything.ru/integrations/yandex-geocoder.md