Геокодирование
Внимание
Геокодирование доступно только в актуальных версиях API.
Как перейти на API 2.1
Класс 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]](https://yandex.ru/dev/maps/archive/doc/jsapi/1.x/ref/reference/geocoderresult.html) реализует интерфейс 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.