Геокодирование

Класс YMaps.Geocoder позволяет отправлять запросы геокодеру, получать информацию о статусе и результате процесса геокодирования, а также получать результаты геокодирования в виде меток.

Конструктор класса принимает два параметра:

• request – строка с адресом, который нужно геокодировать (для обратного геокодирования - точка с географическими координатами);
• options – параметры:
  • boundedBy – область на карте, в которой осуществляется поиск объекта;
  • strictBounds - флаг, указывающий, что искать следует только внутри области, заданной опцией boundedBy;
  • results – требуемое количество результатов поиска (не более);
  • skip – указание пропустить первые n результатов в ответе;
  • prefLang – предпочитаемый язык ответа.

Для повышения релевантности поиска геокодируемых объектов рекомендуется при запросе к геокодеру ограничивать область поиска с помощью параметра boundedBy. Параметр strictBounds включает/выключает ограниченный поиск.

Чтобы определить координаты объекта, создайте экземпляр класса YMaps.Geocoder и передайте ему в качестве параметра строку с адресом объекта. В примере ниже производится поиск всех объектов с названием "Москва":

var geocoder = new YMaps.Geocoder("Москва");
map.addOverlay(geocoder);

В результате исполнения примера, переменная geocoder будет содержать результаты поиска в виде группы специальных меток класса YMaps.GeocoderResult. Эти метки отличаются от обычных меток класса YMaps.Placemark наличием четырех дополнительных полей, в которых передаются дополнительные сведения о найденном объекте:

• kind – вид топонима (улица, дом, город и т.д.);
• precision – предполагаемая точность ответа;
• text – адрес одной строкой;
• AddressDetails - структурированное представление адреса объекта в соответствии со стандартом xAL.

Класс YMaps.GeocoderResult реализует интерфейс YMaps.IOverlay, поэтому метки YMaps.GeocoderResult можно добавлять на карту точно так же, как и обычные.

Для обработки результатов геокодирования необходимо учитывать, что геокодеру требуется время на обработку запроса и ответ. Поэтому рекомендуется всегда использовать обработчики событий для получения информации об окончании геокодирования и о его текущем статусе.

В классе YMaps.Geocoder предусмотрено два события: Load (геокодирование прошло без ошибок) и Fault (с ошибками).

В обработчике события Load можно оперировать результатами геокодирования как группой. Подробнее о работе с группами см. Группировка объектов.

Пример ниже иллюстрирует обработку событий геокодера. В случае успешного геокодирования пользователю карты будет показано сообщение о количестве найденных объектов, а самый релевантный (первый) из них будет показан на карте:

YMaps.Events.observe(geocoder, geocoder.Events.Load, function () {
    if (this.length()) {
        alert("Найдено :" + this.length());
        map.addOverlay(this.get(0));
        map.panTo(this.get(0).getGeoPoint())
    }else {
        alert("Ничего не найдено")
    }
});
 
YMaps.Events.observe(geocoder, geocoder.Events.Fault, function (error) {
    alert("Произошла ошибка: " + error.message)
});

Открыть пример в новом окне

Параметр prefLang геокодера дает возможность контролировать язык результатов поиска.

Этот параметр позволяюет задать предпочтительный язык, на котором будет производиться выдача результатов геокодирования. Код языка указывается в соответствии со стандартом ISO 639.

Список возможных значений:

• ru - русский;
• uk - украинский;
• be - белорусский.

Если установить параметр prefLang в значение “uk”, то в результате поиска адреса «киев, площадь независимости» будет получен результат – «київ майдан незалежності».

var geocoder = new YMaps.Geocoder("Киев, площадь Независимости", { prefLang : "uk" } );
 
YMaps.Events.observe(geocoder, geocoder.Events.Load, function (geocoder) {
    map.addOverlay(geocoder.get(0));
    map.setBounds(geocoder.get(0).getBounds());
});

Открыть пример в новом окне

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

Объект YMaps.Geocoder поддерживает обратное геокодирование, с помощью которого можно преобразовывать координаты объекта в почтовый адрес.

Для обратного геокодирования в параметре request требуется передать вместо адреса геоточку (YMaps.GeoPoint). Пример ниже производит обратное геокодирование координат здания Цетрального телеграфа в Москве и получает его адрес:

// Запускает процесс геокодирования
var geocoder = new YMaps.Geocoder(new YMaps.GeoPoint(37.588395, 55.762718), {results: 1});

// Обработчик успешного завершения процесса геокодирования
YMaps.Events.observe(geocoder, geocoder.Events.Load, function () {
    if (this.length()) {
        map.addOverlay(this.get(0));
        map.panTo(this.get(0).getGeoPoint())
    }else {
        alert("не найдено")
    }
});
 
// Обработчик неудачного завершения геокодирования
YMaps.Events.observe(geocoder, geocoder.Events.Fault, function (geocoder, error) {
    alert("Произошла ошибка: " + error.message)
});

Результаты поиска, как и в случае с прямым геокодированием, возвращаются в виде группы меток класса YMaps.GeocoderResult, которые сразу можно нанести на карту.

Открыть пример в новом окне

В качестве дополнения, в разделе Примеры узнайте, как создать аналог инструмента "Информация", размещенного на странице maps.yandex.ru.