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 Яндекс.Карт и их решения".