Программное геокодирование

Общие сведения

Функция geocode позволяет производить поиск топонимов по адресу или названию, либо определять их адрес по координатам. В функцию можно передать название объекта в виде строки или координаты в виде массива.

Чтобы выполнить геокодирование с помощью функции geocode, вызовите ее и обработайте ответ:

var myGeocoder = ymaps.geocode("Петрозаводск");
myGeocoder.then(function(res) {
    myMap.geoObjects.add(res.geoObjects);
});

В песочнице можно посмотреть интерактивный пример прямого геокодирования.

var myGeocoder = ymaps.geocode([61.79,34.36]);
myGeocoder.then(function(res) {
    myMap.geoObjects.add(res.geoObjects);
});

В песочнице можно посмотреть интерактивный пример обратного геокодирования.

Функция работает асинхронно. Асинхронное взаимодействие реализовано с помощью обещаний (promises):

  • Вызов функции geocode приводит к созданию объекта типа vow.Promise.
  • Когда от сервера вернутся результаты геокодирования или сообщение об ошибке, они будут сохранены в объекте promise.
  • С помощью метода then объект Promise передаст полученный ответ последующим функциям.

Результат поиска

Функция может вернуть результаты поиска в двух форматах:

  • в виде коллекции GeoObjectCollection. Этот объект реализует интерфейс IGeoObject, то есть может быть размещен на карте;
  • в формате JSON. Чтобы получить ответ в таком формате, задайте опции json значение true. Подробнее о формате документа можно посмотреть в статье Ответ геокодера документации HTTP API Геокодера.

Решение типовых задач

Как получить координаты в текстовом формате?

Чтобы получить координаты топонима, произведите обратное геокодирование. Первый элемент в полученном объекте содержит нужный геообъект. Затем можно получить адрес геообъекта в текстовом формате с помощью метода GeoObject.getAddressLine.

// Поиск координат Красной площади.
ymaps.geocode('Красная площадь', {
    results: 1
}).then(function (res) {
        // Выбирает первый результат геокодирования.
        var firstGeoObject = res.geoObjects.get(0),
            // Координаты геообъекта.
            coords = firstGeoObject.geometry.getCoordinates(),
            // Область видимости геообъекта.
            bounds = firstGeoObject.properties.get('boundedBy');

        // Устанавливает необходимый для отображения текста пресет метки.
        firstGeoObject.options.set('preset', 'islands#darkBlueDotIconWithCaption');
        // Получает строку с адресом и выводим в иконке геообъекта.
        firstGeoObject.properties.set('iconCaption', firstGeoObject.getAddressLine());

        // Добавляет первый найденный геообъект на карту.
        myMap.geoObjects.add(firstGeoObject);
        // Масштабирует карту на область видимости геообъекта.
        myMap.setBounds(bounds, {
            // Проверяет наличие тайлов на данном масштабе.
            checkZoomRange: true
        });
    });
Как ограничить область поиска?

Область поиска можно ограничить с помощью опции boundedBy. По умолчанию, заданная область не накладывает жестких ограничений на поиск. Поиск производится по всей карте, но приоритет отдается видимым объектам.

Чтобы искать строго в указанной области, задайте опции strictBounds значение true.

var myGeocoder = ymaps.geocode("Петрозаводск", {
   // Ограничение поиска видимой областью карты.
   boundedBy: myMap.getBounds(),
   // Жесткое ограничение поиска указанной областью.
   strictBounds: true
});
myGeocoder.then(function(res) {
    myMap.geoObjects.add(res.geoObjects);
});      
Как найти ближайшие станции метро?

Чтобы получить информацию о ближайшей к точке станции метро, передайте в метод geocode тип metro и получите первый объект из ответа:

var myCoords = [55.754952,37.615319];
myMap.geoObjects.add(
    new ymaps.Placemark(myCoords,
        {iconContent: 'Где метро?'},
        {preset: 'islands#greenStretchyIcon'}
    )
);
var myGeocoder = ymaps.geocode(myCoords, {kind: 'metro'});
myGeocoder.then(
    function (res) {
        var nearest = res.geoObjects.get(0);
        var name = nearest.properties.get('name');
        nearest.properties.set('iconContent', name);
        nearest.options.set('preset', 'islancds#redStretchyIcon');
        myMap.geoObjects.add(res.geoObjects);
    },
    function (err) {
        alert('Ошибка');
    }
);

Примечание

Если в запросе указан тип топонима, другие типы топонимов игнорируются.

Как определить адрес по клику на карте?

Чтобы определить адрес точки когда пользователь кликает на карте, нужно отслеживать событие нажатия по карте и произвести обратное геокодирование полученных координат:

  // Код ждет клик на карте.
  myMap.events.add('click', function(e) {
    var coords = e.get('coords');

    getAddress(coords);
  });

  // Определение адреса по координатам (обратное геокодирование).
  function getAddress(coords) {
    ymaps.geocode(coords).then(function(res) {
        var firstGeoObject = res.geoObjects.get(0);
        // Обработка координат
        ...
      }

    )}

В песочнице можно посмотреть интерактивный пример.

Примеры в песочнице