Геокодирование
Класс YMaps.Geocoder позволяет отправлять запросы геокодеру, получать информацию о статусе и результате процесса геокодирования, а также получать результаты геокодирования в виде меток.
Конструктор класса принимает два параметра:
- request – строка с адресом, который нужно геокодировать (для обратного геокодирования - точка с географическими координатами);
- options – параметры:
- boundedBy – область на карте, в которой осуществляется поиск объекта;
- strictBounds - флаг, указывающий, что искать следует только внутри области, заданной опцией boundedBy;
- results – требуемое количество результатов поиска (не более);
- skip – указание пропустить первые
n
результатов в ответе; - prefLang – предпочитаемый язык ответа.
Чтобы определить координаты объекта, создайте экземпляр класса 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.