Блог API Яндекс.Карт

февраль 2010
Создание и отображение XML-файла с метками заданного стиля (на примере офисов Яндекса на карте мира)
1 февраля 2010, 15:41
-----
Эта статья относится к API Яндекс.Карт 1.x. Рекомендуем почитать аналогичную инструкцию для новой версии API — 2.0.
-----

Последнее время достаточно часто нас просят помимо документации, рассказывать про различные примеры использования API Яндекс.Карт, с пояснениями каких-либо моментов с фрагментами кода. Время от времени мы будем публиковать такие статьи в этом клубе, а также будем рады видеть нечто подобное и от разработчиков, которые разобрались с нашим АПИ, и хотели бы поделиться опытом с другими веб-разработчиками.

Сегодня мы рассмотрим то, как устроена карта с несколькими метками с заданным стилем на карте мира.

Рассмотрим вот такой пример: Все офисы Яндекса на карте мира

Показать несколько меток на интерактивной карте (как в примере) можно двумя способами: задать их с помощью функций Javascript API (подробнее см. раздел "Метки") или описать их при помощи специального XML-файла ("YMapsML" — Yandex Maps Markup Language).

Первый способ можно использовать тогда, когда html-страница генерируется на сервере, и для метки можно на уровне вызовов Javascript указывать различные параметры. А второй — когда сама страница на сайте статическая, а XML либо сформирована один раз, или генерируется на сервере.

Сегодня мы рассмотрим второй способ добавления меток на карту.

Для этого потребуется создать 2 файла: html — страница на которой помещён вызов карты и все необходимые параметры, чтобы показать метки из xml-файла.

Итак, что потребуется:

1) API-ключ для использования Яндекс.Карт - его нужно получить на этой странице.Кстати, при получении ключа, вам будет предложен простой html-код страницы с картой с центром Москвы и уже с вашим ключом, код можно вставить в пустой HTML-файл на локальном диске или на хостинге, и посмотреть, что получилось.

2) стандартный текстовый редактор или любой другой редактор текста с возможностью править XML и HTML файлы.

3) Если вы хотите использовать для обозначения меток собственные значки, то сами значки и тень для значка. Это может быть любая картинка (gif, png, jpg) для интернета с небольшими размерами.

В нашем примере:

Значок

Тень значка:

Кроме этого, нужно знать какого размера картинки, и координаты точки (в пикселях, от левого верхнего угла), которая должна указывать место на карте — "хвостик" точки.

Создание XML-файла с метками

Рассмотрим уже созданный XML-файл с метками: http://company.yandex.ru/inside/address.xml 

Этот файл состоит из двух основных частей, вложенных в корневой элемент ymapsrepr:Repsentation — здесь задается представление и ymaps:GeoObjectCollection — здесь описываются географические данные (в нашем случае метки).

Подробная схема YMapsML документа здесь 

Обратите внимание, для элементов важно понятие namespace, имена и значения задаются атрибутами xmlns для корневого элемента так:

Это значит, что для того или иного набора тегов будет использоваться соответсвующая схема (правила описания этого тега).


Задание меток

Для того, чтобы описать метку (точку), в тег ymaps:GeoObjectCollection нужно описать вложенный тег:

  <gml:featureMember>
   <ymaps:GeoObject id="taganka">
    <gml:description>
     Москва, ул. Станиславского, дом 21, строение 3
    </gml:description>
    <gml:name>
     Офис Яндекса на Станиславского
    </gml:name>
    <gml:Point>
    <gml:pos>37.662335 55.745376</gml:pos>
     </gml:Point>
    <ymaps:style>#companyStyle</ymaps:style>
   </ymaps:GeoObject>
  </gml:featureMember>

Подробнее о тегах внутри:

ymaps:GeoObject — непосредственно описание геообъекта (точки)

gml:description — описание геообъекта

gml:name — название объекта

gml:Point — указание типа геообъекта "метка"

gml:pos — географические координаты в формате - "долгота широта" (через пробел), например "37.662335 55.745376"

ymaps:style — идентификатор стиля данной метки


Где взять географические координаты?

Если у вас есть почтовый адрес, вы можете задать http-запрос к Геокодеру, либо можно просто узнать их, перетащив метку на карте в этом примере

Задание стиля метки

Стиль метки здается тегом  задаются в теге  repr:Repsentation

<repr:Style gml:id="companyStyle">
        <repr:iconStyle>
            <repr:href>http://company.yandex.ru/i/ya.png</repr:href>
            <repr:size x="57" y="55"/>
            <repr:offset x="-37" y="0"/>
            <repr:shadow>
                <repr:href>http://company.yandex.ru/i/shadow.png</repr:href>
                <repr:size x="57" y="55"/>
                <repr:offset x="-37" y="0"/>
            </repr:shadow>
        </repr:iconStyle>
    <repr:balloonContentStyle>
        <repr:template>#companyTemplate</repr:template>
    </repr:balloonContentStyle>
</repr:Style>

В этом теге:

repr:iconStyle — описание значка для метки, оно содержит тег repr:href — ссылка на картинку со значком. Путь до картинки нужно указывать полностью, с "http://..". А так же: repr:size — размер картинки, и repr:offset — смещение значка от точки на карте.

Если у значка есть тень, то в тег repr:iconStyle нужно вложить тег repr:shadow, в котром также нужно указать href, size и offset.

repr:balloonContentStyle — стиль содержимого всплывающего окна (balloon) по клику на метке, содержит тег repr:template (с маленькой буквы) — идентификатор шаблона.

Сам же шаблон задается с помощью repr:Template (с большой буквы), в данном случае значения $name и $description подставляются в подзаголовок, и текст под ним:

<repr:Template gml:id="companyTemplate">
        <repr:text><![CDATA[<div><h4>$[name]</h4><span>$[description]</span></div>]]></repr:text>
    </repr:Template>

Важно: Созданный YMapsML-файл можно визуализировать с помощью Javascript API только в том случае, если он будет доступен для серверов Яндекса по http. Если сайта у вас пока нет, тестовые xml-файлы вы можете опубликовать, например, на Народе 

Визуализация YMapsML-файла на карте

Рассмотрим интересующие нас вызовы API в коде страницы

Подключение Javascript API

Простое подключение API происходит при помощи загрузки Javascript (внутри тега <head>):
<script charset="utf-8" type="text/javascript" src="http://api-maps.yandex.ru/1.0/?key=API-ключ">

"1.0" — версия API (Подробнее о версиях Javascript API)

"API-ключ" — ключ, полученный для вашего сайта, получить ключ можно здесь, подробнее о ключах — в "Вопросах и ответах" 

Задание параметров карты и вызовы

<script type="text/javascript"><!--
var map; //декларируем имя объекта для карты
var ml; //декларируем имя слоя с метками из XML


function init (lat,long) { //функция имеет входные параметры - широта и долгота, куда спозиционировать карту
    map = new YMaps.Map(document.getElementById("YMapsID") //создание карты
    map.setCenter(new YMaps.GeoPoint(long, lat), 2); //задание параметров для карты (центр и уровень масштабирования)

    ml = new YMaps.YMapsML( 'http://company.yandex.ru/inside/address.xml' //создание слоя с метками из XML

    map.addOverlay(ml); //добавление слоя на карту

    map.addControl(new YMaps.TypeControl() //добавляем элемент управления переключения типов карты
    map.addControl(new YMaps.ToolBar() //добавление тулбара
    map.addControl(new YMaps.Zoom() //добавление элемента управления масштабом
    map.addControl(new YMaps.ScaleLine() //добавление масштабного отрезка

    YMaps.Events.observe(ml, ml.Events.Fault, function (error) {
        alert('Ошибка' + error); //если XML документ не загрузился или загрузился с ошибками, выведется сообщение об этом
    }
};
    //--></script>

Добавление html-элемента с картой на страницу
<div id="YMapsID" style="height:400px; width:100%;"></div>

Инициализация карты

Карта иницилизируется по загрузке страницы, с центром в указанных ниже координатах:

<body onload="init('45.758255','-22.00');">

Это все :)

PS: Пишите вопросы, если чего-то было непонятно.

3 комментария
API 1.x,статьи,YMapsML
Обратное геокодирование
1 февраля 2010, 15:45

===Эта статья относится к старой версии API Яндекс.Карт — 1.х. Рекомендуем использовать API 2.0 Яндекс.Карт.=== 

На прошлой неделе была выпущена новая версия API 1.х, в которой была добавлена возможность обратного геокодирования.

Обратное геокодирование - это процесс преобразования географических координат объекта в почтовый адрес.

Вызов обратного геокодирования отличается от прямого только тем, что вместо строки с адресом передаются координаты объекта.

Осуществлять обратное геокодирование можно с использованием любого из двух интерфейсов: http и javascript.

Пример использования обратного геокодера по http-интерфейсу.
http://geocode-maps.yandex.ru/1.x/?geocode=37.611706,55.75862&key=API-ключ

Пример использования обратного геокодера по javascript-интерфейсу.

var geocoder = new YMaps.Geocoder(new YMaps.GeoPoint(37.611706,55.75862)

map.addOverlay(geocoder);


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

На основе javascript-интерфейса создадим инструмент "Информация".
 
Инструмент "Информация" - это элемент управления, который позволяет по координатам щелчка мыши пользователя определять почтовый адрес объекта (или ближайший адрес к нему). Посмотреть инструмент в действии можно на странице maps.yandex.ru.

Используя javascript-интерефейс, т. е. объект YMaps.Geocoder можно создать аналог инструмента "Информация".

Создадим элемент управления (назовем его InformationControl), для этого реализуем интерфейс YMasp.IControl.

// Элемент управления "Информация"
function InformationControl () {
// Вызывается при добавлении элемента управления на карту
this.onAddToMap = function (parentMap) {}

// Вызывается при удалении элемента управления с карты
this.onRemoveFromMap = function () {}
}

При добавлении элемента управления на карту будет создаваться обработчик щелчков мыши по карте. При щелчке на карту будет добавляться метка с координатами щелчка мыши и результат геокодирования.
// Вызывается при добавлении элемента управления на карту
this.onAddToMap = function (parentMap) {
  map = parentMap;
   
// Создание обработчика кликов по карте
listener = YMaps.Events.observe(map, map.Events.Click, function (map, mEvent) {
// Выключаем обработчиков событий, чтобы к геокодеру ушло не более одного запроса
// (по окончанию геокодированияю включаем обработчик вновь)
listener.disable(

// Координаты клика мышью
var clickPoint = mEvent.getGeoPoint(

 ...

// Отмечаем точку по которой щелкнул пользователь
clickPlace = new YMaps.Placemark(clickPoint, {style: anchorStyle}
clickPlace.description = clickPoint.toString(
map.addOverlay(clickPlace);

// Запуск процесс геокодирования
this.geocode(clickPoint);
}, this);
}

Метод geocode() запускает процесс геокодирования и добавляет результат на карту. В данном методе создаются обработчики для событий геокодера Load и Fault, в которых происходит обработка результатов поиска (в частности, включается обработчиков кликов по карте).
При успешном результате геокодирования наиболее релевантный результат геокодирования (если он был найден с помощью метода getResult()) добавляется на карту. 
 
 // Геокодирует точку
this.geocode = function (clickPoint) {
// Запуск процесса геокодирования
var geocoder = new YMaps.Geocoder(clickPoint);

// Обработчик успешного завершения геокодирования
YMaps.Events.observe(geocoder, geocoder.Events.Load, function (geocoder) {
// Получение результата поиска
geoResult = this.getResult(geocoder);

if (geoResult) {
   map.addOverlay(geoResult);
geoResult.openBalloon(
} else {
alert("Ничего не найдено!");
}

// Включаем обработчик кликов по карте
listener.enable(
}, this);

// Обработчик неудачного геокодирования
YMaps.Events.observe(geocoder, geocoder.Events.Fault, function (geocoder, err) {
alert("Произошла ошибка при геокодировании: " + err);

// Включаем обработчик кликов по карте
listener.enable(
}

Метод getResult() возвращает результат с различной точностью в зависимости от масштаба.
 
// Возвращает результат различной точности в зависимости от масштаба
this.getResult = function (geocoder) {
    // Точность: страна, область, город
    function isCountry (result) {
        return result.kind == "country" || result.kind == "province" || result.kind == "locality";
    }

    // Точность: улица
    function isStreet (result) {
        return result.kind == "street" || result.kind == "district";
    }

    // Точность: дом
    function isHouse (result) {
        return !isCountry(result) && !isStreet(result);
    };

    // Выбор точности поиска
    var filter = isHouse;
    if (map.getZoom() < 10) {
        filter = isCountry;
    } else if (map.getZoom() < 15) {
        filter = isStreet;
    }

    // Возвращает первый найденный результат
    return geocoder.filter(filter)[0];
}
  
Создадим экземпляр созданного класса InformationControl, а также кнопку на панели инструментов, которая позволит включать и выключать созданный элемент управления.
 
// Создание элемента управления "Информация"
var informationControl = new InformationControl(

// Создание новой кнопки
// Добавляем ее к стандартной группе кнопок на панеле инструментов
var buttonInformation = new YMaps.ToolBarRadioButton(YMaps.ToolBar.DEFAULT_GROUP, {
icon: "http://maps.yandex.ru/i/info-button.png",
hint: "Информация"
}

// Включение/выключение инструмента "Информация"
YMaps.Events.observe(buttonInformation, buttonInformation.Events.Select, function () {
map.addControl(informationControl);
}

YMaps.Events.observe(buttonInformation, buttonInformation.Events.Deselect, function () {
map.removeControl(informationControl);
}

// Добавление элементов управления на карту
var toolBar = new YMaps.ToolBar(
toolBar.add(buttonInformation);
map.addControl(toolBar);

Посмотреть пример в действии можно по адресу: http://ymaps.narod2.ru/examples/reversegeocoderinformation.html
Нет комментариев
API 1.x,статьи,геокодирование
Как ограничить область поиска?
1 февраля 2010, 15:46

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

Если задать в поиске "улица Победы", то получим достаточно длинный список из 95 объектов.

Предположим, что необходимо нанести на карту результаты поиска, расположенные только в Москве или Московской области.

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

// Область Москвы и Московской области
var moscowBounds = new YMaps.GeoBounds(
    new YMaps.GeoPoint(37.13268871914181, 55.55945544545429),
    new YMaps.GeoPoint(38.085747336675574, 55.946698202860325)


// По умолчанию геокодер возвращает первые 10 результатов поиска. Спомощью параметра results можно задать максимальное количество возвращаемых результатов.
map.addOverlay(new YMaps.Geocoder("победы", {boundedBy : moscowBounds, results : 100})

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

В решении данной задачи поможет параметр геокодера strictBounds, который указывает, что необходимо производить поиск только внутри области, заданной опцией boundedBy.


Немного изменим код:

// Область Москвы и Московской области
var moscowBounds = new YMaps.GeoBounds(
    new YMaps.GeoPoint(37.13268871914181, 55.55945544545429),
    new YMaps.GeoPoint(38.085747336675574, 55.946698202860325)

map.addOverlay(new YMaps.Geocoder("победы", {boundedBy : moscowBounds, strictBounds : true, results : 100})

В результате работы этого примера на карте будут отображены только те объекты, которые вошли в заданную область.

В http-геокодере можно задать область поиска с помощью параметров ll и spn, а с помощью параметра rspn ограничить поиск только заданной областью.

Более расширенный пример по работе с геокодером можно посмотреть по адресу:

http://ymaps.narod2.ru/examples/geocode-search.html

Нет комментариев
статьи,геокодирование
Добавление градусной сетки на карту
1 февраля 2010, 15:47

На карту можно добавлять не только различные элементы управления и объекты, но и слои.

Слой - это область на карте, собранная из тайлов (прозрачных или с изображением), на которой могут располагаться различные объекты.
С помощью слоев на карте можно отметить зону покрытия сети или отобразить дополнительную информацию.

 Градусная сетка на обзорных масштабах на Яндекс.Картах — пример такого слоя.

Градусная сетка представляет из себя набор линий, опоясывающих земной шар в широтном и меридиональном направлениях, с помощью которой можно точно определить положение любой точки на земной поверхности.

Слой с координатной сеткой можно добавить на карту и на своём сайте. Для этого необходимо создать источник данных для тайлов и передать его в качестве параметра в конструктор класса YMaps.Layer для создания слоя. Более подробно о создании слоев можно прочитать в Руководстве разработчика.

При создании источника для тайлов с помощью класса YMaps.TileDataSource необходимо задать шаблон, по которому будет строиться URL для получения тайла.

В этом шаблоне можно использовать следующие специальные конструкции:

  • %d - заменяется на число от 1 до 4, в зависимости от номера тайла. Используется для распределения нагрузки между несколькими доменами.
  • %c - заменяется на x&y&z, где x - номер тайла по горизонтали, y - номер тайла по вертикали, z - коэффициент масштабирования.

Для построения URL'a тайла воспользуемся второй специальной конструкцией.

// Создание источника данных для тайла
var dataSource = new YMaps.TileDataSource("http://lrs.maps.yandex.net/tiles/?l=grd&v=1.0&%c", true, false),

    // Создание слоя
    gridLayer = new YMaps.Layer(dataSource);

// Добавление слоя на карту
map.addLayer(gridLayer);

Более расширенный пример, с возможностью включения и выключения отображения градусной сетки можно найти по этому адресу:
http://ymaps.narod2.ru/examples/grids.html

2 комментария
градусная сетка,статьи,свой слой
Изменение внешнего вида объектов
1 февраля 2010, 15:48

Стандартный внешний вид меток, балуна, ломанной, многоугольника и всплывающей подсказки можно поменять с помощью стилей.

Стиль – это набор параметров, который позволяет задать внешний вид объектов на карте. Чтобы создать стиль, необходимо создать экземпляр класса YMaps.Style.

Сам стиль является контейнером, содержащем в себе стили для конкретных объектов (значка метки, ломанной линии и т. д.).
Например, за оформление значка метки отвечает поле iconStyle, в которое должен быть записан указатель на объект класса YMaps.IconStyle.

// Создание нового стиля
var style = new YMaps.Style();
 
// Стиль для оформления значка метки
style.iconStyle = new YMaps.IconStyle();
 

При создании любого оверлея в конструктор класса можно передавать как указатель на стиль, так и ключ.

Ключ – это строка, которая является уникальным идентификатором стиля.

В наименовании ключа можно использовать любые символы, однако рекомендуется создавать свое пространство имен и в нем задавать пользовательские стили. Пространство имен и имя стиля разделятся символом "#" (решетка). Все стандартные стили находятся в пространстве имен “default”. Например, «deafult#greenPoint”, «deafult#redPoint”, «deafult#smallWhitePoint” и т. д.

Продемонстрируем на фрагменте кода оба способа задания стиля.

// Создание стиля
// Подробнее о смене значка на любое изображение будет рассказано далее
var style = new YMaps.Style();
style.iconStyle = new YMaps.IconStyle();
style.iconStyle.href = "http://api-maps.yandex.ru/i/0.3/micro/pmgns.png";
style.iconStyle.size = new YMaps.Point(28, 29);
style.iconStyle.offset = = new YMaps.Point(-7, -28);
 
// В конструктор класса передается указатель на стиль
var placemark = new YMaps.Placemark(map.getCenter(), {style : emptyStyle});
 
// Стиль задан с помощью ключа
var placemark2 = new YMaps.Placemark(map.getCenter(), {style : "default#greenPoint"});

Ключ используется для того, чтобы выбрать нужный стиль из хранилища стилей YMaps.Styles.
Использовать хранилище стилей удобно, когда необходимо обращаться к стилям до их создания. Например, когда стили создаются в отдельном файле и загружаются после создания меток.

В хранилище можно добавить свои стили с помощью метода add(), а удалять – с помощью метода remove().

// Добавим созданный стиль в хранилище
YMaps.Styles.add("example#blueIcon", styleExample);

Теперь к добавленному стилю можно получить доступ по его ключу:

var style = YMaps.Styles.get("example#blueIcon");

Стиль можно задавать не только в конструкторе оверлея в виде параметра, но и с помощью метода setStyle().

placemark.setStyle("default#smallRedPoint");

С помощью метода setStyle() можно менять стиль оверлеев динамически во время выполнения скрипта.

Рассмотрим подробнее механизм стилей на примере смены значка у метки.

В API существует ряд стандартных, предопределенных стилей для значков с различными цветовыми решениями и размерами. Полный их список приведен в Справочнике по программному интерфейсу.

Возьмем стандартный стиль с ключом «deafult#greenPoint» и зададим его метке, тем самым поменяем цвет стандартного значка с светлого-голубого на зеленый.

var placemark = new YMasp.Placemark(map.getCenter(), {style : "default#greenPoint"});
map.addOverlay(placemark);

В качестве значка метки можно использовать любое пользовательское изображение.

Сменим значок на произвольное изображение.
Для этого необходимо создать экземпляр класса YMaps.IconStyle и определить у него три поля: ссылку на изображение (href), размер значка (size) и смещение изображения относительно точки позиционирования значка (offset).

// Создание стиля для метки
var styleExample = new YMaps.Style();
styleExample.iconStyle = new YMaps.IconStyle();
styleExample.iconStyle.href = "http://info.maps.yandex.net/api/i/steelblue/dot.png";
styleExample.iconStyle.size = new YMaps.Point(26, 46);
styleExample.iconStyle.offset = new YMaps.Point(-22, -46);
 
// Создание метки с измененным значком
var placemark = new YMasp.Placemark(map.getCenter(), {style : styleExample});
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

Создадим пустой стиль:

var styleEmpty = new YMaps.Style();

Если применить вышеприведенный стиль к любому из оверлеев, то их внешний вид не изменится, хотя подстили не были определены.

Дело в том, что недостающие стили наследуются от родительского. Если родительский стиль не указан, то недостающие стили берутся из параметров по умолчанию.

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

Рассмотрим наследование стилей. Для этого разместим на карте несколько меток со значками футбольного, баскетбольного и теннисного мячей. Их размеры одинаковы и равны 20х20 px. Чтобы не дублировать описание стилей для каждой метки, создадим базовый стиль, который будет содержать информацию о размерах и смещении меток. Стили всех меток унаследуем от базового стиля.

// Создание базового стиля
var baseStyle = new YMaps.Style();
baseStyle.iconStyle = new YMaps.IconStyle();
baseStyle.iconStyle.offset = new YMaps.Point(-10, -10);
baseStyle.iconStyle.size = new YMaps.Point(20, 20);
 
// Наследуемся от базового стиля
var styleFootBall = new YMaps.Style(baseStyle);
styleFootBall.iconStyle = new YMaps.IconStyle();
styleFootBall.iconStyle.href = "/img/football.png";
 
// Наследуемся от базового стиля
var styleBasketBall = new YMaps.Style(baseStyle);
styleBasketBall.iconStyle = new YMaps.IconStyle();
styleBasketBall.iconStyle.href = "/img/basketball.png";
 
// Наследуемся от базового стиля
var styleTennis = new YMaps.Style(baseStyle);
styleTennis.iconStyle = new YMaps.IconStyle();
styleTennis.iconStyle.href = "/img/tennis.png";

Посмотреть пример отдельном окне 

Для элементов группы можно задать единый стиль. Для этого нужно передать ключ стиля (или указатель на стиль) в качестве параметра в конструктор класса YMaps.GeoObjectCollection и он будет применен ко всем элементам группы автоматически (стиль для группы можно также задать с помощью метода setStyle()):

var gCollection = new YMaps.GeoObjectCollection("default#greenPoint");

Посмотреть пример в отдельном окне

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

// Для всех меток группы задается зеленый значок
var gCollection = new YMaps.GeoObjectCollection("default#greenPoint");
gCollection.add([
    // У этой метки определен стиль - красный значок
    // Стиль группы не перекроет стиль этого объекта
    new YMaps.Placemark(new YMaps.GeoPoint(37.518234,55.708937), {style: "default#redPoint"}),
    new YMaps.Placemark(new YMaps.GeoPoint(37.514146,55.722294))
]));

Таким образом группа будет содержать две метки с красным и зеленым значками соответственно.

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

Рассмотрим цепочку наследования из трех стилей. В первом определим стиль обводки многоугольника, во втором – стиль заливки, а в третьем – стиль для значка метки. Пусть третий стиль наследуется от второго, а второй – от первого.

// Стиль обводки многоугольника
var stylePolygonOutline = new YMaps.Style();
stylePolygonOutline.polygonStyle = new YMaps.PolygonStyle();
stylePolygonOutline.polygonStyle.outline = true;
stylePolygonOutline.polygonStyle.strokeColor = "0000ff88";
stylePolygonOutline.polygonStyle.strokeWidth = 3;
 
// Стиль заливки многоугольника
// Наследуется от stylePolygonOutline
var stylePolygon = new YMaps.Style(stylePolygonOutline);
stylePolygon.polygonStyle = new YMaps.PolygonStyle();
stylePolygon.polygonStyle.fill = true;
stylePolygon.polygonStyle.fillColor = "0000ff33";
 
// Стиль значка метки
// Наследуется от stylePolygon
var styleIcon = new YMaps.Style(stylePolygon);
styleIcon.iconStyle = new YMaps.IconStyle();
styleIcon.iconStyle.href = "http://info.maps.yandex.net/api/i/steelblue/dot.png";
styleIcon.iconStyle.size = new YMaps.Point(26, 46);
styleIcon.iconStyle.offset = new YMaps.Point(-22, -46);

Теперь если применить третий стиль (styleIcon) к группе, состоящей из метки и многоугольника, то внешний вид обоих объектов будет изменен:

// Создание группы с заданным стилем для значка метки и многоугольника
var group = new YMaps.GeoObjectCollection(styleIcon);
group.add([
    new YMaps.Placemark(map.getCenter()),
    new YMaps.Polygon([new YMaps.GeoPoint(37.53, 55.77), new YMaps.GeoPoint(37.53, 55.83),new YMaps.GeoPoint(37.75, 55.83)])
]);
map.addOverlay(group);

Посмотреть пример в отдельном окне 

Создавать стили можно как обычные объекты Javascript, т. е. без вызова конструктора. Перепишем стиль styleIcon.

var styleIcon = {
    parentStyle : stylePolygon,
    iconStyle : {
        href : "http://info.maps.yandex.net/api/i/steelblue/dot.png",
        size : new YMaps.Point(26, 46),
        offset : new YMaps.Point(-22, -46
    }
}

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

 
Нет комментариев
статьи,наследование стилей,стили
Формирование ссылки на фрагмент карты
1 февраля 2010, 15:48

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

Рассмотрим как можно менять адрес страницы, используя JavaScript. Для манипуляций с адресом страницы обратимся к глобальному объекту document.location, который содержит информацию об адресе текущего документа. Адрес текущей загруженной страницы можно изменить, используя свойство href объекта document.location.

Адрес на текущий фрагмент карты будем сохранять в HTML-элементе «Ссылка» в атрибуте href. Код для создания данного HTML-элемента выглядит следующим образом:

<a id="YMapsLink" href="#">Получить ссылку на карту</a>

Чтобы сформировать адрес на фрагмент карты, необходимо сохранять в ссылке центр карты, линейный размер области, а также тип карты.

Для перевода типа карты в строковое представление и обратно напишем небольшой класс TypeConverter, для перевода остальных параметров воспользуемся стандартным методом toString().

// Конвертер типов карт
// Если тип карты не был определен, то по умолчанию возвращается тип карты YMaps.MapType.MAP (или имя "map")
function TypeConverter () {
        // Доступные типы карты
    var types = [YMaps.MapType.MAP, YMaps.MapType.SATELLITE, YMaps.MapType.HYBRID],
 
        // Имена карт
        names = ["map", "sat", "hyb"];
 
    // Возвращает имя карты по ее типу
    this.typeToName = function (type) {
        return names[valid(YMaps.jQuery.inArray(type, types))];
    };
 
    // Возвращает тип карты по имени
    this.nameToType = function (name) {
        return types[valid(YMaps.jQuery.inArray(name, names))];
    };
 
    // Проверяет правильность полученного индекса
    function valid (index) {
        return (index == -1) ? 0 : index;
    }
};

Теперь приступим к формированию адреса на фрагмент карты. Сделать это несложно, для этого необходимо установить обработчики для событий карты BoundsChange и TypeChange.

// Динамически формируем URL
YMaps.Events.observe(map, [map.Events.BoundsChange, map.Events.TypeChange],  function () {
    YMaps.jQuery("#YMapsLink")
        .attr("href", "?l=" + typeConverter.typeToName(map.getType()) +
                      "&ll=" + map.getCenter().toString() +
                      "&spn=" + map.getBounds().getSpan().toString(6)
        );
});

В итоге ссылка будет иметь следующий вид:

?l=hyb&ll=37.664725,55.842762&spn=0.823971,0.309084

Напишем код, который будет обрабатывать параметры из ссылки и изменять параметры карты.

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

// Получение параметра из URL'а
function getParam (name, location) {
    location = location || window.location.hash;
    var res = location.match(new RegExp('[#&]' + name + '=([^&]*)', 'i'));
    return (res && res[1] ? res[1] : '');
}

Далее создадим объект, который будет содержать все параметры, обнаруженные в URL'е.

// Получаем параметры из URL'а
var params = {
    ll : getParam("ll"),    // Центр карты
    spn : getParam("spn"),  // Линейный размер области
    t : getParam("t")       // Тип карты
};

С помощью метода fromString() можно создать объекты классов YMaps.GeoPoint и YMaps.Size из строкового представления.

По координатам центра и линейному размеру области с помощью метода класса YMaps.GeoBounds fromCenterAndSpan() можно определить область, которую необходимо отобразить на карте.

// Центрируем карту в нужном месте
map.setBounds(YMaps.GeoBounds.fromCenterAndSpan(YMaps.GeoPoint.fromString(params.ll), YMaps.Size.fromString(params.spn)));

Тип карты из строкового вида в объект переводим с помощью описанного выше класса TypeConverter:

// Устанавливаем требуемый тип карты
map.setType(typeConverter.nameToType(params.l));

Посмотреть пример в новом окне 

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

Посмотреть пример в новом окне

 

Нет комментариев
статьи,события,ссылка на карту
Текстовые шаблоны
1 февраля 2010, 15:49

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

Текстовый шаблон – это HTML-строка (верстка), которая может содержать элементы вида $[имя_поля|значение_по_умолчанию]. Такие элементы заменяются данными из объекта-контекста, который передается в метод build() при разборе конкретного шаблона.

Под объектом-контекстом понимается объект, из которого должны браться данные для подстановки. Если объект не содержит данных, путь к которым указан в элементе, то элемент будет заменен пустой строкой или значением по умолчанию, если оно указано. Значение по умолчанию указывается сразу после символа "|".

Создадим свой шаблон для значка метки.

// Создание текстового шаблона для метки
var template = new YMaps.Template('<div><img src="http://info.maps.yandex.net/api/i/steelblue/dot.png"/>\
<div class="b-point-name">$[name|0]</div></div>');

Свяжем стиль с созданным текстовым шаблоном и применим его к метке.

// Создание стиля для значка метки
var styleIcon = new YMaps.Style();
 
// В конструктор стиля значка метки передается указатель на текстовый шаблон
styleIcon.iconStyle = new YMaps.IconStyle(template);
 
// Создание метки
var placemark = new YMaps.Placemark(map.getCenter(), {style: styleIcon});
placemark.name = 5;
 
// Добавление метки на карту
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

Примечание. Текстовые шаблоны можно добавлять в хранилище, тогда обращаться к ним можно будет по ключу. Это может потребоваться в том случае, если шаблоны создаются после определения стилей.
 
YMaps.Templates.add("example#customPointIcon", template);
 
Тогда создание стиля можно будет записать так:
 
styleIcon.iconStyle = new YMaps.IconStyle("example#customPointIcon");
 

Таким образом значок для метки может быть не только изображение, а любое html-содержимое, которое будет задано в текстовом шаблоне.

Например, рассмотрим следующую задачу: для каждой метки в балуне нужно выводить заголовок зеленым цветом, а под описанием объекта – размещать логотип компании.
Можно решить эту задачу, записав необходимый html для каждого объекта в поля name и desctiption. Тогда определение содержимого одной метки будет выглядеть примерно так:

// Создание метки
var placemark = new YMaps.Placemark(map.getCenter());
 
// Определение содержимое балуна метки
placemark.name = '<span style="color: green">Имя объекта</span>';
placemark.description = '<div>Описание объекта</div><img src="http://img.yandex.ru/i/m_logo.png" alt=""/>';
 
// Добавление метки на карту
map.addOverlay(placemark);

Посмотреть пример на отдельной странице 

Однако, если таких объектов будет много (например, около сотни), то для того, чтобы изменить оформление выводимой информации (например, убрать логотип компании из описания объекта), необходимо будет изменить сотню строчек кода. Это неудобно. Лучше для этих целей создать текстовый шаблон содержимого балуна и применить его ко всем меткам.

Рассмотрим подробнее текстовый шаблон балуна по умолчанию.

<b>$[name]</b><div>$[description]</div>

Элементы name и description будут браться из объекта контекста. Если вызвать метод openBalloon() у метки, то объектом-контекстом будет сама метка.

var placemark = new YMaps.Placemark(map.getCenter());
placemark.name = "Имя объекта";
placemark.description = "Описание объекта";
 
map.addOverlay(placemark);
placemark.openBalloon();

 В итоге после построения шаблона балун будет иметь следующее содержимое:

<b>Имя объекта</b><div>Описание объекта</div>

Изменим текстовый шаблон содержимого балуна и на его основе создадим стиль. Стили можно создавать как обычные объекты JavaScript, поэтому воспользуемся этой возможностью для сокращения записи.

var style = {
    balloonContentStyle : {
        template : new YMaps.Template('<b style="color: green">$[name]</b><div>$[description]</div>\
        <img src="http://img.yandex.ru/i/m_logo.png" alt=""/>')
    }
}

Теперь применим созданный стиль к метке.

var placemark = new YMaps.Placemark(map.getCenter(), {style: style});
placemark.name = "Имя объекта";
placemark.description = "Описание объекта";
 
map.addOverlay(placemark);

 Посмотреть пример на отдельной странице 

В итоге получен результат такой же, как если html был записан в поля name и description. Текстовые шаблоны позволяют избавляться от дублирования код (в текстовый шаблон можно вынести все повторяющиеся элементы, например, цвет заголовка и логотип компании).

Кроме того в текстовых шаблонах можно задавать значения по умолчанию, которые также могут помочь.

Например, стоит задача: разместить на карте местоположения складов, а в балуне указывать количество единиц товара, которые на них в настоящее время присутствует. Если товара нет (количество единиц товара равно нулю), то необходимо вывести сообщение «нет в наличии». Дополнительную информацию необходимо размещать в поле metaDataProperty, чтобы избежать перекрытия стандартных полей и методов.

var style = {
    balloonContentStyle : {
        template : new YMaps.Template('<b>$[name]</b><div>$[description]</div>\
        <div>Количество товара: $[metaDataProperty.anyMetaData.count|нет в наличии]</div>')
    }
}
 
var placemark = new YMaps.Placemark(map.getCenter(), {style: style});
placemark.name = "Склад № 1";
placemark.description = "Центральный склад, расположенный в центре карты";
 
// Добавление дополнительной информации
placemark.metaDataProperty = {
    count : 100
}
 
map.addOverlay(placemark);

Если не определить поле placemark.metaDataProperty.count, то будет выведено сообщение по умолчанию «нет в наличии».
Посмотреть пример на отдельной странице

Использование текстовых шаблонов позволяет гибко изменять внешний вид объектов на карте и создавать оверлеи с уникальным внешним видом. Также в шаблоны можно вынести общую информацию и верстку для всех объектов, избавляясь от дублирования кода и делая код более гибким и универсальным
Нет комментариев
текстовые шаблоны,статьи
Приветствуем вас в Блоге API Яндекс.Карт
1 февраля 2010, 15:58

Рады видеть вас в блоге команды разработки API Яндекс.Карт. Здесь мы пишем обо всем новом, что происходит на сервисе, публикуем анонсы мероприятий и другую полезную информацию.

В блоге легко ориентироваться: вы сразу найдете интересующие вас темы по меткам.

Например, с меткой «статьи» мы выкладываем тексты наших разработчиков или ссылки на материалы пользователей об API Яндекс.Карт и о его возможностях.

С меткой «примеры» мы публикуем новые примеры использования API, которых пока нет в документации.

Если вас интересуют прошедшие и предстоящие мероприятия, на которых мы рассказываем про API, обратите внимание на метки «конференции» и «вебинар». А материалы докладов ищите по меткам «видео» и «презентации».

Чтобы открыть собственную тему, задать вопрос разработчикам, использующим API Яндекс.Карт, или опубликовать свою статью, воспользуйтесь клубом разработчиков API Яндекс.Карт.

Сайт API Яндекс.Карт
Документация API Яндекс.Карт
Страница API Яндекс.Карт в Facebook
Страница API Яндекс.Карт во ВКонтакте

Нет комментариев
Официальные инструменты Яндекс.Карт — API 1.x
1 февраля 2010, 16:34

-----

Эта статья относится к API Яндекс.Карт 1.x. Рекомендуем почитать аналогичную инструкцию для новой версии API — 2.0.

-----

API Яндекс.Карт используется для реализации множества различных сервисов: от простых схем проезда до почти полноценных ГИС. В зависимости от сложности решаемой задачи и «динамичности» данных, отображаемых на карте, используется свой подход и инструменты.

Схемы проезда обычно не меняются, а создаются один раз на продолжительный промежуток времени (например, до переезда офиса). Поэтому для их создания удобно воспользоваться визуальным инструментом «Конструктор схем проездов", который позволяет разметить необходимые объекты на карте и получить готовый код для вставки на страницу.

Недостатком «Конструктора схем проезда» является отсутствие возможности продолжить редактирование созданных карт. Поэтому для изменения объектов или их местоположение приходится создавать либо новую карту в конструкторе, либо редактировать JavaScript вручную. Такой проблемы не возникнет при использовании сервиса «Мои карты".

Сервис «Мои карты» позволяет отмечать на карте метки, изменять их внешний вид и описание, после чего можно поделиться ссылкой на созданную карту с друзьями. Карту, созданную в вышеописанном сервисе, можно разместить и у себя на сайте. Для этого необходимо воспользоваться возможностью экспорта объектов, размеченных на карте, в виде YMapsML. Более подробно про экспорт YMapsML можно прочитать в этом топике.

Чтобы добавить YMapsML-документ на карту, необходимо после ее инициализации вставить следующую строку (необходимо подставить свой URL):

Посмотреть пример на отдельной странице

Объекты, размещенные на карте таким образом, можно редактировать через интерфейс «Моих карт». Другими словами все изменения, внесенные в карту на Яндекс.Картах, автоматически отразятся в соответствующем YMapsML.

При добавлении YMapsML-документа из "Моих карт" центр и масштаб карты подбирается таким образом, чтобы все добавленные метки были видны на карте. Такое поведение можно изменить, если при создании YMapsML в конструктор передать параметр viewAutoApply со значением false. 

map.addOverlay(

    new YMaps.YMapsML("http://maps.yandex.ru/export/usermaps/DwSVPt66C9uouT5tN_0YgE-D23KX7rM0/", {

        viewAutoApply : false

    })

Посмотреть пример на отдельной странице 

После окончания загрузки YMapsML-документа можно поменять внешний вид значков. Для этого необходимо создать обработчика события Load и в нем вызвать метод setStyle() для группы, в которой размещены метки:

var ml = new YMaps.YMapsML("http://maps.yandex.ru/export/usermaps/DwSVPt66C9uouT5tN_0YgE-D23KX7rM0/");

map.addOverlay(ml);

 

YMaps.Events.observe(ml, ml.Events.Load, function (ml) {

    ml.get(0).setStyle("default#mushroomIcon");

} 

Посмотреть пример на отдельной странице 

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

Нет комментариев
API 1.x,инструменты
72 примера использования API 1.x Яндекс.Карт на одной странице
3 февраля 2010, 10:42

В клубе API Яндекс.Карт, при личных встречах вы нас часто просили сделать больше примеров, потому что, лучше один раз увидеть чем сто раз услышать!

Конечно, мы пошли на встречу вашим пожеланиям и сегодня рады представить обновленную страницу примеров использования JavaScript API 1.x Яндекс.Карт.
Теперь примеров аж 72 штуки и они разбиты на 16 групп, чтобы было удобнее найти нужный.

Группы отсортированы по сложности. Поэтому, чтобы увидеть в примерах весь процесс создания сложного проекта, просто начните сверху от "Основ использования карты" и просмотрите всё до блока "Карты, координатные системы".

Мы собрали все примеры о которых вы нас просили.

Нужно что-то ещё? Обязательно пишите!
Эта страница будет пополняться на основе ваших пожеланий.

Нет комментариев
API 1.x,примеры
API Яндекс.Карт в вопросах и ответах
12 февраля 2010, 17:50
Список вопросов и ответов на основе обсуждений клуба API Яндекс.Карт.
API Яндекс.Карт в вопросах и ответах

В нашем клубе мы обсуждаем много различных вопросов и решаем интересные задачи. На многие вопросы были найдены ответы, которые могут пригодиться новым разработчикам. Для того, чтобы облегчить поиск готовых решений, мы решили подготовить список часто задаваемых вопросов и ответов на них.

Вопросы в этом списке были разбиты на категории для более быстрой и удобной навигации.

Приведенный ниже список будет переодически пополняться и обновляться. Мы надеемся, что он сослужит вам добрую службу.

API-ключ

  1. Можно ли получить ключ для домена первого уровня?

  2. Как показывать API для сайта и его зеркал?

  3. Можно ли вести разработку и отладку API на локальной машине?

Карта

  1. Как установить карту на сайт?

  2. Как разместить несколько карт на одной странице?

  3. Типы карт «Схема» и «Спутник не совпадают. Как это можно исправить?

  4. Как сделать ссылку на текущий фрагмент карты?

  5. Есть ли ограничение по количество обращений к карте?

  6. У меня вместо карты отображается серый прямоугольник. Что делать?

  7. Как получить список городов для которых есть подробная карта?

  8. Как вставить карту в блог?

Координаты

  1. Я вдруг в Африке. Что делать?

  2. Как преобразовать географические координаты в тайловые и обратно?

  3. Почему координаты на Google Maps и Яндекс.Картах разные?

  4. Как рассчитать расстояние между двумя точками на карте?

  5. Как определять местоположения пользователя в зависимости от IP?

Элементы управления

  1. Что делать если кнопки элемента управления обрезаны или смещены?

  2. Как добавить свои кнопки на панель инструментов или удалить стандартные?

  3. Как изменить текст в SearchControl'e?

Объекты-оверлеи на карте

  1. У балуна появились отступы, растянулся во всю ширину карты, съехала тень и др.

  2. Есть ли в API встроенный редактор объектов?

  3. Как отключить замену img на div в IE 6?

  4. Сколько меток можно отображать на карте, чтобы не страдала производительность?

  5. Как можно реализовать поиск по объектам, добавленным на карту?

  6. Как задать содержимое значка метки при использовании своего шаблона?

  7. Как сделать меню и связать его с объектами на карте?

  8. Есть ли в API группировка меток с одинаковыми координатами?

  9. Я записал в поле description новое значение, но в балуне эти изменения не отобразились.

  10. В IE6 не отображаются ломаные или многоугольники или отображаются через раз.

Слои

  1. Можно ли подключить слой развязок, панорам или видеокамер в API?

  2. Как обновить все тайлы, отображенные в видимой области карты ?

  3. Как создать свой слой карты и нарезать правильно тайлы?

  4. Как менять порядок слоев, используя z-index?

  5. Как создать слой для определенного масштаба?

  6. Как нанести сетку на слой, который не будет двигаться?

Сервисы

  1. Как получить доступ к результатам геокодирования/маршрутизатора?

  2. Можно ли получить список домов по заданной улице/области?

  3. Как реализовать множественное геокодирование объектов?

  4. В каких тегах YMapsML можно использовать html?

  5. Можно ли инициализировать карту результатами геокодирования?

  6. Как получить список городов для которых есть подробная карта с точностью до дома?

  7. Как заставить искать геокодер в определенной стране/городе?

  8. Как перебрать все объекты загруженного YMapsML-документа?

  9. Какой входной формат адреса для геокодера?

Другоe

  1. При вставке кода карты с использованием CMS она не отображается. Что делать?

 

API-ключ

  1. Можно ли получить ключ для домена первого уровня?
    Ключ можно получить для домена, в имени которого содержится точка и хотя бы по одному символу до и после точки. Например, “mysite.ru”, “dev.localhost”.
    При получении ключа поддомен “www” автоматически вырезается, таким образом при вводе адреса "www.site.ru", ключ будет получен для домена “site.ru”.

  2. Как показывать API для сайта и его зеркал?
    Если у сайта есть доменные зеркала, то для того, чтобы загрузка API работала одновременно и на страницах основного сайта, и на страницах зеркал в параметр key следует добавить API-ключи зеркал сайта через тильду ("~"). Подробнее можно почитать в
    Руководстве разработчика.

  3. Можно ли вести разработку и отладку API на локальной машине?
    Да, это возможно.
    Вам нужно получить ключ для своего локального домена и укажите его при
    подключении API.
    При создании локально домена учтите, что имя домена должно содержать в себе точку и хотя бы по одному символу до и после нее (для доменов первого уровня ключи не выдаются). Тaким образом вместо домена http://mysite/ создайте, например, http://dev.mysite/.
    Кстати, для IP адреса также можно получить ключ, поэтому если вам это будет удобнее, то можете использовать при разработке его.
    Из вышеописанного правила есть два исключения - это домены http://localhost/ и http://127.0.0.1/. Для них отдельно необязательно получать ключ, а можно использовать любой рабочий (например, от вашего сайта).
    Также при разработке в браузере можно отключить отправку referrer, тогда сообщение о неправильном ключе не будет отображаться. В браузерах Mozilla Firefox и Opera это сделать легко (одним щелчком мыши), а в браузере IE такой возможности не предусмотрено (можно поставить firewall и не пропускать referrer'ы).

 

Карта

  1. Как установить карту на сайт?
    http://api.yandex.ru/maps/doc/jsapi/1.x/dg/tasks/quick-start.xml

  2. Как разместить несколько карт на одной странице?
    http://api.yandex.ru/maps/doc/jsapi/1.x/articles/tasks/map.xml#how-to-add-multiple-maps

  3. Типы карт «Схема» и «Спутник не совпадают. Как это можно исправить?
    В некоторых городах у нас наблюдается подобный эффект из-за неточности данных от поставщиков карт. Мы стараемся это исправлять и публиковать новые, более точные карты по мере возможности. В основном мы выравниваем спутниковые снимки по схеме, т. е. схемы более точные.

  4. Как сделать ссылку на текущий фрагмент карты?
    http://api.yandex.ru/maps/doc/jsapi/1.x/articles/tasks/map.xml#how-to-create-link-to-map-fragments

  5. Есть ли ограничение по количество обращений к карте?
    Количество обращений к карте неограниченно, есть только ограничение на количество обращений к геокодеру: 25000 запросов в сутки с одного API-ключа.

  6. У меня вместо карты отображается серый прямоугольник. Что делать?
    Причин возникновения подобной проблемы может быть несколько. Основных три:

    1. Карта не инициализирована (необходимо вызвать метод setCenter()).
    2. Карта показана из скрытого контейнера (необходимо вызвать метод redraw() для перерисовки карты). Пример.
    3. Конфликт стилей css (например, если задать стиль img {width:100%}).

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

  7. Как получить список городов для которых есть подробная карта?
    Список городов для которых есть подробные карты и снимки на Яндекс.Картах можно увидеть здесь
    http://maps.yandex.ru/?index

  8. Как вставить карту в блог?
    Большая часть блогхостеров запрещают использовать JavaScript, поэтому интерактивную карту вставить скорее всего не получится. Однако, вы можете воспользоваться StaticAPI и вставить изображение карты в блог. Подробную информацию о Static API можно найти в разделе
    Документация, а также воспользоваться инструментом «Конструктор схем проезда», который позволяет в визуальном режиме создать такую карту.

 

Координаты

  1. Я вдруг в Африке. Что делать?
    Если у вас карта центрируется в атлантическом океана около Африки, то это означает, что Вы задали нулевые координаты. Именно в этом месте находится точка отсчета.

  2. Как преобразовать географические координаты в тайловые и обратно?
    Сделать подобные преобразования поможет класс
    YMaps.TileCoordinates. С помощью метода fromCoordPoint координатной системы можно получить пиксельные координаты точки, которые потом нужно передать в метод fromPixels() класса YMaps.TileCoordinates.
    Экземпляры классов YMaps.TileCoordinates и YMaps.ICoordSystem содержатся в полях tileCoordinates и coordSystem объекта карты.

    // Преобразовывает географические координаты в пиксельные
    var pixelsCoords = map.coordSystem.fromCoordPoint(map.getCenter()),
         // Получает из пиксельных координат индекс тайла и смещение относительно его верхней левой точки
         tile = map.tileCoordinates.fromPixels(pixelsCoords, map.getZoom()

    alert("Центра карты находится в тайле № " + tile.number + " со смещением в " + tile.offset.toString()

     

  3. Почему координаты на Google Maps и Яндекс.Картах разные?
    Координаты используются одинаковые, только порядок разный. В картах Google используется нотация latlong (широта, долгота), а в Яндекс.Картах – longlat (долгота, широта).

    var googlePoint = new GLatLng(37.4419, -122.1419), // Геоточка в Google Maps
         yandexPoint = new YMaps.GeoPoint(-122.1419, 37.4419, // Геоточка в Яндекс.Картах
    Порядок longlat используется в большинстве GIS систем. Связано это с тем, что в связке широта и долгота, долгота является горизонтальной осью, т.е x, а широта – осью y, и если привести к стандартным (x, y) получится (долгота, широта).
    KML использует порядок долгота/широта (KML Reference).
    <coordinates>...</coordinates> <!-- lon,lat[,alt] -->
    ...
    A geographic location defined by longitude, latitude, and (optional) altitude.
    У нас, как и у всех, используется проекция EPSG:4326, по спецификации порядок – latlong, но в большей части GIS мира используется longlat. В мире GIS систем нет строго определения порядка следования координат: используют и долгота/широта, и широта/долгота.

    Ссылки по теме:
    http://geoserver.org/display/GEOSDOC/2.+WFS±+Web+Feature+Service#2.WFS-WebFeatureService-Theaxisorderissue
    http://www.postgis.org/documentation/manual-svn/ST_AsGML.html

     

  4. Как рассчитать расстояние между двумя точками на карте?
    Для расчета кратчайшего расстояния между двумя точками на карте необходимо воспользоваться методом
    distance() координатной системы, используемой на карте. Например, метод distance() географической координатной системы, либо через метод distance() геоточки.
    Длину пути по локсодроме (прямые в проекции Меркатора не являются кратчайшими путями) можно измерить с помощью инструмента «Линейка», либо через метод rulerDistance() координатной системы.

  5. Как определять местоположения пользователя в зависимости от IP?
    В API такого функционала в настоящее время нет.
    Вам необходимо иметь соответствующую базу данных соответствия IP какой-нибудь локации на карте.
    Есть
    бесплатные базы (у них точность малая, пример использования здесь) и есть платные (которые более точны).
    Также существуют бесплатные сервисы, которые предоставляют сервис получения информации по IP-адресу, например, Smart-IP API.

 

Элементы управления

  1. Что делать если кнопки элемента управления обрезаны или смещены?
    Это проблема верстки. CSS-стили на вашем сайте перекрывают стили элемента управления. Воспользуйтесь DOM-инспектором и исправьте ошибку.

  2. Как добавить свои кнопки на панель инструментов или удалить стандартные?
    При создании панели инструментов можно указать какие кнопки необходимо отображать.

    var toolbar = new YMaps.ToolBar([new YMaps.ToolBar.MoveButton(), new YMaps.ToolBar.MagnifierButton()] // Создание панели инструментов без кнопки "Линейка"
    Добавлять и удалять кнопки можно после создания панели инструментов с помощью методов add() и remove() соотвественно. Подробнее можно прочитать в Руководстве разработчика.

     

  3. Как изменить текст в SearchControl'e?
    В настоящее время этого сделать нельзя.

 

Объекты-оверлеи на карте

  1. У балуна появились отступы, растянулся во всю ширину карты, съехала тень и др.
    Это проблема верстки. CSS-стили на вашем сайте перекрывают стили API Яндекс.Карт. Воспользуйтесь DOM-инспектором (например, для браузера Firefox -
    Firebug) и исправьте ошибку. Чаще всего подобные конфликты вызываются стилями, установленными для элементов table, tr, td. В этом случае задайте уточняющее правило, заменив общее правило на более частное. Например, правило

    td {padding: 5px}
    можно заменить на
    td.myClass {padding: 5px}

     

  2. Есть ли в API встроенный редактор объектов?
    Объекты-оверлеи поддерживают
    режим редактирования, в частности для метки можно включить режим перетаскивания.
    Также можете воспользоваться нашим сервисом Мои карты, в которых можно редактировать метки, а также экспортировать YMapsML с данными для размещения на своем проекте.

  3. Как отключить замену img на div в IE 6?
    В метод setBaloonContent можно передать свой макет (ILayout), внутри которого все в вашей власти.
    Посмотрите
    пример использования.

  4. Сколько меток можно отображать на карте, чтобы не страдала производительность?
    Мы рекомендуем отображать не более 100 меток на карте.
    В случае большого количества меток воспользуйтесь
    Диспетчером объектов, который позволяет скрывать метки вне видимой области карты, давая тем самым выйгрыш в производительности.
    Если же количество объектов исчисляется сотнями, то без разработки серверных скриптов не обойтись. Например, создайте скрипт, который будет в качестве параметров принимать масштаб и область просмотра карты и генерировать YMapsML-документ/JSON с объектами, которые попали в данную область. Таким образом пользователям будет отдавать лишь часть данных, а не все сразу.
    Пример реализации: http://probki.avtoradio.ru.

  5. Как можно реализовать поиск по объектам, добавленным на карту?
    Добавьте объекты в
    группу, а затем отфильтруйте необходимые с помощью метода filter().

  6. Как задать содержимое значка метки?
    Для того, чтобы задать содержимое значка метки воспользуйтесь методом
    setIconContent().

    placemark.setIconContent("Щелкни меня");
    Подробнее читайте в Руководстве разработчика.

    При использовании своего шаблона теряется возможность изменять содержимое значка метки с помощью метода setIconContent(). Поэтому лучше создать своймакет. Преимущество макетов в том, что они позволяют задать поведение шаблонам. Таким образом содержимое значка метки можно будет задавать с помощью стандартного метода setIconContent().
    Посмотрите пример с использованием шаблона и макета.

     

  7. Как сделать меню и связать его с объектами на карте?
    Подробно процесс создания меню описан в примере по созданию элемента управления
    «Путеводитель по офисам» и «Как использовать плавное перемещение центра карты».

  8. Есть ли в API группировка меток с одинаковыми координатами?
    На настоящий момент, если добавить 2 и более метки на карту, то они перекроют друг друга. Сверху будет та, что добавлена последней. Например,

    var pl = new YMaps.Placemark(map.getCenter()
    pl.setBalloonContent('pl');
    map.addOverlay(pl);

    var pl2 = new YMaps.Placemark(map.getCenter()
    pl2.setBalloonContent('pl2');
    map.addOverlay(pl2);

    var pl3 = new YMaps.Placemark(map.getCenter()
    pl3.setBalloonContent('pl3');
    map.addOverlay(pl3);

    Таким образом щелкнуть можно будет только на pl3.

     

  9. Я записал в поле description новое значение, но в балуне эти изменения не отобразились.
    При изменении содержимого полей name и description, необходимо вызывать метод
    update(), чтобы изменения вступили в силу.

  10. В IE6 не отображаются ломаные или многоугольники или отображаются через раз.
    Для избежания подобной проблемы необходимо в тег html прописать пространство имен vml.

    <html xmlns:vml="urn:schemas-microsoft-com:vml">

     

 

Слои

  1. Можно ли подключить слой развязок, панорам или видеокамер в API?
    Нет, такие данные в API на текущий момент не предоставляются.

  2. Как обновить все тайлы, отображенные в видимой области карты ?
    Необходимо изменить шаблон урла в tileDataSource (например, добавить какой-нибудь GET-параметр со случайным числом) и вызвать метод карты
    update().

  3. Как создать свой слой карты и нарезать правильно тайлы?
    Изображения карты нужного разрешения необходимо порезать на тайлы, используя принятые на картах Яндекса шаблоны
    URL, либо свою. Во втором случаем Вам придется переопределить метод getTileUrl(). За более подробной информацией обращайтесь в раздел Пользовательские карты.
    Для нарезки тайлов можно воспользоваться специальной программой.

  4. Как менять порядок слоев, используя z-index?
    У слоя есть метод
    getContainer(). Манипулируя z-index-ом HTML-элемента, который возращает этот метод, Вы можете переставлять слои. По умолчанию все добавленные пользователем слои имеют одинаковый z-index, значение которого хранится в константе YMaps.ZIndex.MAP_LAYER.

  5. Как создать слой для определенного масштаба?
    При переопределении метода getTileUrl() модно добавить дополнительное условие, которое позволит отображать слой только на конкретном масштабе. Например:

    var myData = new YMaps.TileDataSource("http://mt.gmapuploader.com/tiles/FVSH1JsvdT/", true, true);
    myData.getTileUrl = function (tile, zoom) {
         if (zoom == 3) {
              return this.getTileUrlTemplate() + "/tile-" + zoom + "-" + (tile.y * Math.pow(2, zoom) + tile.x) + ".jpg";
         } else {
              return this.getErrorTileUrl(
         }}
    В итоге на 3 масштабе поверх карты будет отображаться дополнительный слой. Осталось этот слой добавить на карту:
    map.addLayer(new YMaps.Layer(myData)
    Можно поступить по-другому: слушать событие Update карты и при необходимом значении коэффициента масштабирования добавлять слой на карту, в противном случае – удалять его с карты. В этом случае никаких дополнительных условий в методе getTileUrl() прописывать не надо.
    var myLayer = new YMaps.Layer(myData);
    YMaps.Events.observe(map, map.Events.Update, function () {
         if (map.getZoom() == 3 && !myLayer.getMap()) {
              map.addLayer(myLayer);
         } else if (myLayer.getMap()) {
              map.removeLayer(myLayer);
         }
    }

     

  6. Как создать слой, объекты на котором не будут двигаться?
    Создайте свой слой, реализовав интерфейс ILayer. Посмотриет
    пример слоя, который располагает в центре карты зеленый квадратик.

 

Сервисы

  1. Как получить доступ к результатам геокодирования/маршрутизатора?
    Геодирование и маршрутизация – это асинхронные процессы, поэтому необходимо слушать соответствующие события окончания загрузки. Например, для геокодирования это события Load и Fault.
    Пример.

  2. Можно ли получить список домов по заданной улице/области?
    Нет, через API такое сделать нельзя.

  3. Как реализовать множественное геокодирование объектов?
    Стандартного инструмента в API нет. Геокодер может обрабатывать только один адрес (или геоточку, если используется обратное геокодирование).
    Важно! Если при отображении карты геокодировать множество адресов, то информация будет доступна только через некоторое время. Лучше все адреса геокодировать (например, с помощью http-геокодера), закэшировать и отображать объекты по координатам, а не по адресу.
    Множественное геокодирование можно реализовать на любом из серверных языков программирования, используя http-геокодер. Также можно это сделать и с использованием javascript-геокодера. Пример реализации можно посмотреть
    тут.

  4. В каких тегах YMapsML можно использовать html?
    В теге description и шаблонах можно использовать html. В остальных тегах html-разметка экранируется.

  5. Можно ли инициализировать карту результатами геокодирования?
    Да, такое возможно сделать.
    Пример.

  6. Как получить список городов для которых есть подробная карта с точностью до дома?
    см.
    Как получить список городов для которых есть подробная карта?

  7. Как заставить искать геокодер в определенной стране/городе?
    При создании объекта класса YMaps.Geocoder можно указать в параметр boundedBy (область на карте, где предположительнонаходится искомый объект) и флаг strictBounds (искать только в области, определенной в параметре boundedBy). Тогда поиск будет идти именно в этой области. Подробнее можно почитать в статье
    «Как ограничить область поиска».

  8. Как перебрать все объекты загруженного YMapsML-документа?
    YMapsML-документ, добавленный на карту, представляет из себя YMaps.GeoObjectCollection, поэтому перебрать все объекты в него загруженные можно так:

    var ml = new YMaps.YMapsML('http://api.yandex.ru/maps/ymapsml/examples/parentstyleobject.xml'
    map.addOverlay(ml);

    YMaps.Events.observe(ml, ml.Events.Load, function () {
         ml.get(0).forEach(function (obj) {
              alert(obj.description);
         }
    }

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

     

  9. Какой входной формат адреса для геокодера?
    Для входной информации у геокодера используется следующий формат (любой из пунктов может отсутствовать):

    [страна] – Росиия; Украина
    [область, республика, край] – Московская область; республика Дагестан; Алтайский край
    [район внутри области] – Орехово-Зуевский район
    [Город] – Москва; Нижний Новгород; Киев
    [район города] – Москва, ЦАО
    [город внутри города] – Москва, Зеленоград
    [микрорайн, квартал] – Зеленоград, 16-й микрорайон
    [улица] – Костромская улица
    [километр] – МКАД, 18-ый километр
    [дом, строение, корпус, объект] – Москва, ул. Самокатная, дом 1, строение 21; станция Андроновка

     

 

Другоe

  1. При вставке кода карты с использованием CMS она не отображается. Что делать?
    При использовании CMS необходимо вставлять код карты в режиме редактирования html-кода. В противном случае многие CMS вместо переносов строк вставляют html-теги (например, <br>), что вызывает синтаксическую ошибку javascript.
    Также стоит обратить внимание, что некоторые CMS удаляют парные html-теги, в которых отсутствует контент. Т. к. во всех примерах используется пустой контейнер для карты, то в итоге он может быть удален. Можете попробовать добавить комментарий внутрь контейнера с картой. Например,

    <div id="YMapsID" style="widht:400px;height:400px"><!--карта--></div>
    Либо запишите туда какой-нибудь текст. Например,
    <div id="YMapsID" style="widht:400px;height:400px">map</div>
    Возможно, что в вашей CMS можно изменить настройки таким образом, чтобы пустые контейнеры не удалялись.

    Более подробную информацию вы сможете найти на странице "Проблемы при использовании API Яндекс.Карт и их решения".

Нет комментариев
faq,вопросы и ответы
Создание простого редактора меток
16 февраля 2010, 14:52

В данной статье будет рассмотрен процесс создания простого редактора меток. Разрабатываемый редактор позволит осуществлять добавление и перемещение меток в заданную географическую точку, смену их внешнего вида и удаление. Также  редактор позволит формировать ссылки на созданные карты с метками.

Создаваемый редактор можно разбить на несколько обособленных частей, каждая из которых будет решать свой набор задач:

  • PointsClicker – класс, предназначенный для создания и хранения меток;
  • EditInterfaceLayout – интерфейс редактирования параметров метки, представляющий из себя макет для содержимого балуна;
  • PointsManager – класс, позволяющий осуществлять экспорт информации о метках в строковое представление, а также обратное преобразование.

Рассмотрим каждую из описанных частей более подробно.

PointsClicker позволяет включать и выключать режим добавления новых меток с помощью методов  enable() и disable() соответственно.

При вызове метода enable() создается обработчик события Click на карте, который позволяет расставлять метки по щелчку мыши, а при вызове метода disable() – обработчик события Click удаляется.

// Класс для включения/выключения режима "Установка точек"
function PointsClicker (map) {
        // Группа меток, добавленных на карту
    var group = new YMaps.GeoObjectCollection(),
 
        // Слушатель щелчков по карте
        listenerClicker;
 
    // Добавление группы с метками на карту
    map.addOverlay(group);
 
    // Возвращает  группу с метками
    this.getGroup = function (){
        return group;
    };
 
    // Включает режим добавления меток
    this.enable = function () {
 
        // Создание слушателя щелчков по карте
        listenerClicker = YMaps.Events.observe(map, map.Events.Click, function (map, mEvent) {
            var placemark =  this.createPoint(mEvent.getGeoPoint()
            placemark.openBalloon(
        }, this);
    };
 
    // Создает метку на карте
    this.createPoint = function (point, style)  {
        //
        // Создание новой метки
        //
    };
 
    // Выключает режим добавления меток
    this.disable = function () {
        listenerClicker.cleanup(
    }
}

Изначально PointsClicker не представляет визуальных средств для включения и выключения режима добавления новых меток. Поэтому создадим кнопку «Установка точек» на панели инструментов, которая позволит этот режим включать и выключать. Кнопку добавим к стандартной группе радиокнопок, а также зададим ей свой значок и всплывающую подсказку. За более подробной информацией о панеле инструментов обращайтесь в Руководство разработчика.

// Создание панели инструментов
var toolBar = new YMaps.ToolBar(
map.addControl(toolBar);
           
// Элемент управления "Добавление меток"
var clicker = new PointsClicker(map);
 
// Кнопка "Добавление меток"
var button = new YMaps.ToolBarRadioButton(YMaps.ToolBar.DEFAULT_GROUP, {
    icon : "http://api.yandex.ru/i/maps/tools/draw/add_point.png",
    width : 20,
    hint: "Установка точек"
}
toolBar.add(button);
 
// При активной кнопке включаем добавление меток
YMaps.Events.observe(button, button.Events.Select, function () {
    map.addCursor(YMaps.Cursor.POINTER);
    clicker.enable(
})
 
// При неактивной - выключаем
YMaps.Events.observe(button, button.Events.Deselect, function () {
    map.removeCursor(YMaps.Cursor.POINTER);
    clicker.disable(
})

Интерфейс редактирования параметров метки разместим в балуне, который будет отображаться при щелчке по метке. Реализуем его, используя механизм макетов и назовем EditorInterfaceLayout.  В контексте решаемой задачи макеты полезны тем, что позволяют выделить интерфейс редактирования в отдельную логическую единицу. Это даст возможность легко поменять интерфейс редактирования в случае необходимости.

Для создания макета, необходимо реализовать интерфейс YMaps.ILayout.

// Класс макета для содержимого балуна
function EditorInterfaceLayout (context, map, owner) {
    this.editorInterface = this.getEditorInterface(
    this.context = context;
}
 
EditorInterfaceLayout.prototype = {
   // Вызывается при открытии балуна
    onAddToParent : function (parentNode) {
        this.editorInterface.appendTo(parentNode);
        this.update(
    },
 
    // Вызывается при закрытии балуна
    onRemoveFromParent : function () {
        this.editorInterface.remove(
    },
 
    // Обновление содержимого балуна
    update : function () {
        //
        // В данном методе разместим обработчики интерфейса редактирования
        //
    },
 
    // Возвращает jQuery-объект интерфейса редактирования
    getEditorInterface : function () {
        //
        // Создание jQuery-объекта с интерфейсом редактирования
        //
    }
}

Класс PointsManager позволяет преобразовать координаты и описание меток, добавленных на карту с помощью PointsClicker, в строковое представление и обратно. Используя в качестве основы статью Формирование ссылки на фрагмент карты и данный класс, можно формировать ссылки на карту с нанесенными на нее метками.

Класс PointsManager имеет два метода fromString() и toString() с помощью которых и делаются вышеописанные преобразования.

// Класс для преобразования описаний меток в строковое представление и обратно
function PointsManager (clicker) {
 
    // Перевод из строки в объекты на карте
    this.fromString = function (str) {
        //
        // Код для перевода строки в объекты
        //
    };
 
    // Возвращает строку с описанием меток
    this.toString = function () {
        //
        // Код для перевода описаний объектов в строке
        //
    }
}

Окончательный пример можно посмотреть по адресу:

http://ymaps.narod2.ru/examples/mapeditor-simple.html 

В данной статье был рассмотрен процесс создания самого простого из возможных редакторов. Функциональность предложенного редактора можно легко расширить или изменить под свои конкретные нужды, например, добавить возможность редактирования для многоугольников и ломаных.

 
1 комментарий
API 1.x,статьи,макеты,редактор меток
Поддержка KML и GPX в API Яндекс.Карт
19 февраля 2010, 10:40
Теперь на карте можно визуализировать геоданные из таких популярных форматов как KML и GPX.
Добавление KML на карту доступно, начиная с версии 1.1.6, а GPX-треков - с версии 1.1.7.
Поддержка KML и GPX в API Яндекс.Карт

Сегодня опубликована новая версия API Яндекс.Карт 1.1.7.

Начиная с этой версии в JavaScript API поддерживаются два XML-формата: KML и GPX.
Это открытые форматы описания геоданных о поддержке которых нас просили многие пользователи.

Поддержка GPX означает что вы можете показать на карте практически любой GPS-трек в этом формате.

Формат KML поддерживается на уровне позволяющем реализовать большинство его применений на web-сайтах.

Конечно, мы не планируем на этом останавливаться и продолжим расширение поддержки популярных форматов данных.

KML и GPX добавляются на карту по аналогии с YMapsML-файлами с помощью метода карты addOverlay(). Примеры загрузки KML и GPX можно посмотреть на странице примеров или по прямым ссылкам:
http://api.yandex.ru/maps/jsapi/examples/visualisationkml.html
http://api.yandex.ru/maps/jsapi/examples/visualisationgpx.html

Подробнее об изменениях произошедших в версии вы можете прочитать в Списке изменений.

Мы всегда рады новым идеям и пожеланиям. Пишите и ваша интересная идея может быть реализована в очередной версии API Яндекс.Карт.

1 комментарий
API 1.x,KML,обновление,GPX
Доклад "Яндекс.Карты на вашем сайте" на UWDC2010
24 февраля 2010, 14:19

27-28 февраля в Челябинске пройдёт конференция уральских веб-разработчиков UWDC2010.

На конференции мы будем читать доклад "Яндекс.Карты на вашем сайте".

Рассказ будет про инструментарий API Яндекс.Карт, возможности его применения веб-разработчиками разной степени подготовки, примеры использования в интернет-проектах разной степени сложности.
Доклад в двух частях: общий обзор и рассмотрение технологий в технических деталях.

Будем рады видеть вас на этой конференции и на нашем докладе.

Как всегда, мы ответим на все ваши вопросы, даже если для этого придётся сидеть до вечера )


Докладчики Андрей Кармацкий и Сергей Константинов

Нет комментариев
конференции
«Использование Яндекс.Карт в стартапах» доклад на StartupPoint
24 февраля 2010, 16:12

28 февраля пройдёт 16-я встреча StartupPoint в Москве. Местро проведения МИРБИС.

На этом мероприятие вы сможете послушать доклад "Использование Яндекс.Карт в стартапах":

 - возможности в API Яндекс.Карт
 - юридические разрешения
 - возможности монетизации

Приходите, будет интересно!

Традиционно, докладчик не покинет мероприятие пока не ответит на все ваши вопросы )


Выступающий Шныр Леонид

Нет комментариев
конференции
Примеры проектов использующих Яндекс.Карты
26 февраля 2010, 11:59

Сегодня мы открываем страницу примеров проектов интересно использующих API Яндекс.Карт.

Пока таких проектов 9. Все они похожи тем, что используют Яндекс.Карты. Но одновременно они и отличаются друг от друга, потому что используют разные возможности API Яндекс.Карт.

Ожидаемый вопрос "А как мне попасть на эту страницу?". Очень просто! Сделайте проект который будет не похож по применению Яндекс.Карт на все из перечисленных. Напишите нам по адресу support@api-maps.yandex.ru  с пометкой "в каталог проектов".

В ожидание интересных проектов, команда API!

2 комментария
Определение местоположения с использованием Geolocation API
27 февраля 2010, 13:39

-----
Эта статья относится к API Яндекс.Карт 1.x. Рекомендуем посмотреть пример для API 2.0.
-----

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

На многих веб-сайтах задача определения координат пользователя решается с помощью преобразования IP адреса в координаты. Однако, такой способ дает малую точность, которая может не устроить пользователей вашего проекта. В данной статье будет рассмотрен другой способ получения информации о местоположении пользователя – Geolocation API, предложенный W3C.

На сегодняшний день, геолокация поддерживается лишь несколькими браузерами, наиболее популярные из них:

  • FireFox 3.1 и выше;
  • Opera 10.6 и выше;
  • Safari для iPhone (версия ОС 3.1. и выше);
  • Для браузеров Safari и Chrome - для поддержки GeolocationAPI требуется установить дополнительные модули.

Geolocation API предоставляет высокоуровневый интерфейс для получения координат местоположения устройства, предоставляющего доступ в интернет. API не зависит от средств получения информации о местоположении. Эта информация может быть получена при помощи GPS, сетевых параметров (IP адрес, RFID, WiFi адрес или ID ячейки GSM/CDMA), а также введена пользователем. Поэтому, информация полученная с помощью Geolocation API, является более точной, чем простое определение координат по IP адресу.

Интерфейс Geolocation API представляет два метода по определению местоположения пользователя: getCurrentPosition() и watchPosition(). Второй метод отличается от первого только тем, что после окончания вызова и возврата результата, продолжает отслеживать изменения местоположения устройства. Поэтому в случае, если необходимость в отслеживании местоположении отпала, то слушатель нужно удалить с помощью метода clearWatch(). В качестве параметра в метод clearWatch() передается идентификатор слушателя, возвращаемого методом watchPosition().

Получить доступ к интерфейсу Geolocation API можно через объект navigator.geolocation.

В методы getCurrentPosition() и watchPosition() передаются идентичные параметры (последние два из которых являются необязательными)

  • обработчик успешного получения координат;
  • обработчик неудачного получения координат;
  • объект с опциями.

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

  • enableHighAccuracy – отвечает за включение/выключения режима получения самых точных доступных данных. При включенном режиме запрос выполняется более длительный промежуток времени, однако точность будет выше. По умолчанию данный режим отключен;
  • timeout – максимальное время ожидания ответа в миллисекундах. По умолчанию Infinity (бесконечность);
  • maximumAge – время на которое кэшируются полученные данные. По умолчанию это значение равно 0, т. е. данные не кэшируются.

Например, вызывать метод getCurrentPosition() можно так:

navigator.geolocation.getCurrentPosition(
 
    // Обработчик успшеного получения координат
    function (position) {
        alert("Координаты: " + position.coords.longitude + ", " + position.coords.latitude);
    },
   
    // Оработчик неудачного завершения получения коордиант
    function (error) {
        alert("При определении координат произошла ошибка. Ее код: " + error.code);
    },
   
    // Параметры
    {
        enableHighAccuracy : false,     // Режим получения наиболее точных данных
        timeout : 10000,                // Максиальное время ожидания ответа (в миллисекундах)
        maximumAge : 1000               // Максимальное время жизни полученных данных
    }

Сделаем специальную кнопку, по нажатию на будет сформирован запрос на определение местоположения. Кнопка будет видна лишь в тех браузерах, в которой поддерживается эта технология.

Отнаследуемся от стандартной кнопки (класс YMaps.ToolBarButton) c помощью функции extend(

// Реализует наследование прототипа без исполнения конструктора родителя
// Подробнее о наследовании: http://javascript.ru/tutorial/object/inheritance
function extend (child, parent) {
    var c = function () {};
    c.prototype = parent.prototype;
    c.prototype.constructor = parent;
    return child.prototype = new c(
};

Класс кнопки будет выглядеть вот так:

// Кнопка "Геолокатор"
function GeolocatorButton (content, options) {
    // Переданный контент и параметры дополняем значениями по умолчанию
    this.content = YMaps.jQuery.extend({}, this.defaultContent, content);
    this.options = YMaps.jQuery.extend({}, this.defaultOptions, options);
 
    // Вызов родительского конструктора
    YMaps.ToolBarButton.call(this, this.content.normal);
}
 
// Наследование прототипа родителя
var ptp = extend(GeolocatorButton, YMaps.ToolBarButton);
 
//
// Определение различных констант и значений по умолчанию:
// defaultContent
// defaultOptions
// Errors
//
 
// Вызывается при добавлении кнопки на карту
ptp.onAddToToolBar = function (toolBar, parentContainer, group) {
    YMaps.ToolBarButton.prototype.onAddToToolBar.call(this, toolBar, parentContainer, group);
 
    // Указатель на карту
    this.map = toolBar.getMap(
 
    // Проверка поддерживает ли браузер Geolocation API
    if (navigator.geolocation) {
        this.geolocation = navigator.geolocation;
 
        this.listener = YMaps.Events.observe(this, this.Events.Click, this.getPosition, this);
    } else {
        this.hide(
    }
};
 
// Вызывается при удалении кнопки с карты
ptp.onRemoveFromToolBar = function () {
    YMaps.ToolBarButton.prototype.onRemoveFromToolBar.call(this);
 
    this.listener.cleanup(
 
    if (this.placemark) {
        this.map.removeOverlay(this.placemark()
        this.placemark = null;
    }
 
    this.listener = this.geolocation = this.content = this.options = this.map = null;
};
 
// Получает местоположение пользователя
ptp.getPosition = function () {
    //
    // Определение местоположения с использованием GeoLocation API
    //
};

Использовать данный класс совсем просто:

// Создание панели инструментов со стандартным набором кнопок
var toolBar = new YMaps.ToolBar(
 
// Добавление кнопки "Геолокатор"
toolBar.add(new GeolocatorButton()
 
// Добавление панели инструментов на карту
map.addControl(toolBar);

Посмотреть пример на отдельной странице

Geolocation API в настоящее время поддерживается далеко не всеми браузерами, однако, этот способ определения координат заслуживает внимания. В ближайшем будущем большая часть браузеров будет предоставлять рассмотренное API, позволяя разработчикам использовать этот удобный и достаточно точный способ определения местоположения пользователей.

12 комментариев
статьи,geolocation api