Апи яндекс карт конструктор

Обновлено: 30.04.2024

Мне довелось допиливать небольшой проект(~500h), в котором на старте было принято решение использовать Yandex.Maps API, потому что зачем для Москвы использовать гугл карты, если есть наши. Сейчас расскажу, как все прошло.

Я не проводил глубоких подкапотных исследований и никаких секретов не открою. Но, если вам, как и мне, надо очень быстро (вчера) начать использовать в вашем проекте карты, надеюсь, помогу сэкономить немного времени.

Если лень читать или сразу нужен вывод, отправляю в последнее “Действие 4: Это конец / TL;DR”

Действие 0: Определения

Начнем с определений: что, зачем, почему.

Задача: отобразить карту Москвы, пинами указать конкретные места, уметь построить маршрут от текущего положения до конкретной точки (или до нескольких).
Технология: Yandex.Maps API. Ссылки на документацию[1] ниже.
Итого: прочитайте документацию, реализуйте фичи.

Все выглядит просто, что может пойти не так.

Действие 1: Поиск

В “. /maps” [4] нас ждут только бесконечный поиск, разочарование и страдания. Которые к нужной документации меня так и не привели.

Возвращаемся на шаг назад, листаем вниз и находим MapKit [5] — нам сюда. Навигация тут довольно грустная, поэтому вот важные ссылки — android samples [6] и Documentation [7] (возможно, иногда получится найти тут что-то полезное).

Действие 2: Поехали

Находим Getting started и приступаем. В начале все просто.

На “Step 3. Set up the library” возникают вопросы. Вью и фабрику нужно обязательно стартовать и останавливать отдельно, иначе, как нам сообщают, ничего не будет работать. Почему? А что будет, если что-то стартану, а что-то нет, или стартану что-то позже? А если несколько вьюх, то для каждого надо фабрику, или это синглтон?

Возможно, это всего лишь QuickStart и дальше мы найдем подробное описание! (нет)

Давайте смотреть, что есть по документации. А все, ничего больше нет. Есть только сгенерированная документация с комментариями типа:

Ладно, на гитхабе есть еще проект с примерами использования [8]. Внутри каждого класса активити есть комментарии о том, что он делает и зачем нужен (после документации это просто подарок судьбы). Есть несколько сценариев: создание кастомного слоя карты, построение маршрута для автомобиля, работа с объектами на карте и некоторые другие.

Выглядит ли апи мощным? Да.
Понятно ли как им пользоваться в случаях, чуть более сложных, чем примеры? Нет.(
Как это понять? ¯_(ツ)_/¯ Нырять с головой в код, по итогу исследований продавать книжку о том, что нашел.

Действие 3: Разрабатываем

Задача 1: отобразить карту
Сложностей не встретил, все есть в гайде.

Задача 2: отобразить пины
Нам нужен “MapObjectsActivity.java", то, что мы ищем, называется Placemarks. Смотрим в код, чтобы понять, что с ними делать.

Задача 3: построить маршрут
Наш друг тут — “MasstransitRoutingActivity.java”. Маршрут можно попросить разный: только на машине, только пешком, и так и сяк; наверняка можно еще учесть метро и другие разные штуки, но я недонырнул.

Дополнительная задача: позиционирование прямое и обратное. Надо же еще уметь определять местоположение. Прямое геокодирование — определять координаты по названию, обратное — определять название по координатам.

Действие 4: Это конец / TL;DR

Общие итоги:
Яндекс карты классные. Как ими пользоваться — непонятно.

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

Основные моменты:
Как отобразить карту в проекте? Ссылка [7], тут всё просто.
Как добавить пин на карту? Ключевые слова Placemark, MapObjects. Искать в samples.
Как построить маршрут? Ключевое слово MasstransitRouting. Искать в samples.
Как сделать что-то еще? Искать в samples. Если там нет, то у вас проблемы.

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

Чтобы разместить карту на странице, достаточно вставить на эту страницу код виджета, сформированный конструктором.

С помощью Конструктора можно создать два типа карт: интерактивную и статическую. Для интерактивной карты Конструктор формирует элемент script , который подгружает на страницу JavaScript-код для создания карты. Для статической карты Конструктор формирует элемент img , который содержит ссылку на страницу, выполняющую переадресацию 301 с указанными параметрами карты на Static API.

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

Через API Конструктора карт нельзя изменять код виджета, сформированный с помощью элемента iframe .

Интерактивная карта

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

um — идентификатор карты (обязательный параметр).

Пример значения параметра: um=constructor%3A834e99a97453487e0b040c9619.. .

Примечание. В предыдущих версиях Конструктора идентификатор карты задавался через параметр sid . Пример: sid=29uD3jKC-8XFdTlfCwkxSmnSQkYPbrYH . Этот параметр является устаревшим.

width — ширина карты в пикселях или процентах. Если параметр не задан, карта растягивается по всей ширине родительского контейнера;

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

id — идентификатор DOM-элемента, в который нужно вставить карту. Указывается в том случае, если виджет вставлен на страницу в элемент <head> .

lang — локаль. Поддерживаются следующие значения: ru_RU (по умолчанию), ru_UA, uk_UA, en_RU, en_US, tr_TR. Подробнее в разделе Локализация карты.

apikey — ключ от API Карт. Если API-ключ не указан, на карте не будут отображаться элементы управления: поисковая строка, кнопки для построения маршрутов и просмотра панорам.

Примечание. Виджет может быть добавлен как в элемент body , так и в элемент head . Если код вставлен в элемент head , то в атрибуте src необходимо указать параметр id .

Если один и тот же код с одинаковым id вставлен на страницу несколько раз, то в DOM-элемент с указанным id будут вставлены все карты.

Ниже рассмотрены различные примеры размещения на странице интерактивной карты.

Пример 3. Вставка интерактивной карты в контейнер с заданными размерами

Статическая карта

Статическая карта вставляется на страницу с помощью элемента img . Параметры карты, которые могут быть заданы в атрибуте src :

um — идентификатор карты (обязательный параметр).

Пример значения параметра: um=constructor%3A834e99a97453487e0b040c9619.. .

apikey — ключ от API Карт. Необходимо передавать в случае, если карта используется в коммерческих целях. Подробнее см. в разделе Использование платной версии API.

Ниже рассмотрены примеры размещения статической карты на странице.

Использование платной версии API

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

Платная версия распространяется как на интерактивные, так и на статические карты.

Для использования платной версии API со статической картой необходимо в коде элемента указать параметр apikey — API-ключ, полученный в кабинете разработчика. Например:

Через API Конструктора карт нельзя изменять код виджета, сформированный с помощью элемента iframe .

Интерактивная карта

um — идентификатор карты (обязательный параметр).

Пример значения параметра: um=constructor%3A834e99a97453487e0b040c9619.. .

Ниже рассмотрены различные примеры размещения на странице интерактивной карты.

Пример 3. Вставка интерактивной карты в контейнер с заданными размерами

Статическая карта

um — идентификатор карты (обязательный параметр).

Пример значения параметра: um=constructor%3A834e99a97453487e0b040c9619.. .

Ниже рассмотрены примеры размещения статической карты на странице.

Использование платной версии API

Платная версия распространяется как на интерактивные, так и на статические карты.

Map Constructor is an easy-to-use online tool for creating maps with directions and marking places on maps. You can put the maps you create on your website or blog. You can also use these maps in accordance with the Commercial API.

To display a map on a webpage, just copy the widget code generated by the Map Constructor and embed it on the page.

You can use the Map Constructor to create two kinds of maps: interactive and static. For interactive maps, the Map Constructor generates a script element, which loads the JavaScript code for creating the map to the page. For a static map, the Map Constructor generates the img element, which contains a link to a page that performs a 301 redirect to the Static API with the specified map parameters.

The Map Constructor API lets you change the map settings by passing the desired parameters in the widget code. For example, you can set the map height and width, as well as its language.

You cannot change the Map Constructor widget code that is generated by using the iframe element.

Interactive map

The interactive map is embedded on the page using the script element. The following map parameters can be set using the src attribute:

um — the map ID (required).

Example of parameter value: um=constructor%3A834e99a97453487e0b040c9619.. .

Note. In previous versions of the Map Constructor, the map ID was set in the sid parameter. Example: sid=29uD3jKC-8XFdTlfCwkxSmnSQkYPbrYH . This parameter has been deprecated.

width — The width of the map in pixels or percentages. If this parameter is omitted, the map stretches to the entire width of the parent container.

id — The ID of the DOM element to embed the map in. Specified if the widget is inserted on the page in the element .

lang — The locale. The following values are supported: ru_RU (default), ru_UA, uk_UA, en_RU, en_US, tr_TR. For more information, see the section Map localization.

apikey — Maps API key. If the API key is not specified, the map will not display the following controls: the search bar, button for the route building, and panoramas.

Note. The widget can be inserted in either the body element or the head element. If the widget code is in the head element, the id parameter must be specified in the src attribute.

If the same widget code with the same id is inserted on a page multiple times, all the maps will be added to the DOM element with the specified id .

Several examples of embedding an interactive map on a page are shown below.

Example 3. Embedding an interactive map in a container with set parameters

Static map

A static map is inserted on a page using the img element. Map parameters that can be set in the src attribute:

um — the map ID (required).

Example of parameter value: um=constructor%3A834e99a97453487e0b040c9619.. .

Note. In previous versions of the Map Constructor, the map ID was set in the sid parameter. Example: sid=29uD3jKC-8XFdTlfCwkxSmnSQkYPbrYH . This parameter has been deprecated.

lang — The locale. The following values are supported: ru_RU (default), ru_UA, uk_UA, en_RU, en_US, tr_TR. For more information, see the section Map localization.

apikey — Maps API key. Required if the map is used for commercial purposes. See the Using the commercial version of the API section for more information.

The examples below demonstrate placing a static map on a page.

Using the commercial version of the API

The Commercial API is intended for commercial purposes. You can use it in closed systems, applications, and software modules. The paid version lifts some restrictions of the standard license.

The commercial version applies to both interactive and static maps.

To use the commercial version of the API with a static map, the element code must specify the parameter apikey — The API key obtained in developer console. For example:

Перед разработчикам, которые используют API Яндекс.Карт, довольно часто встаёт задача отобразить много объектов на карте. Действительно много — порядка 10 000. Причем эта задача актуальна и для нас самих — попробуйте поискать аптеки на Яндексе. На первый взгляд кажется: «А в чем собственно проблема? Бери да показывай». Но пока не начнешь этим заниматься, не поймешь, что проблем на самом деле целый вагон.

Мы сами внутри Яндекса до недавнего времени советовали смежным командам различные «хаки» и приемы для показа множества точек через API. Яркие примеры – Яндекс.Недвижимость и Яндекс.Такси.

Пункт 1. В чем собственно проблема?

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

Теперь усложняем задачу. У нас есть база данных, в которой хранятся адреса болельщиков «Зенита». И мы хотим показать на карте адреса этих болельщиков.

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

Вес файла index.html увеличится до нескольких Мб и у пользователя страница будет открываться по несколько секунд.
Зачем передавать на клиент ВСЮ базу, если нужно показать только метки для Москвы?
Зачем рисовать на карте ВСЕ метки, если человек увидит только десятую их часть?
Если на карте нарисовать около 100-200 меток обычным способом, карта будет тормозить.
Можно загружать метки постепенно, пачками, чтобы канал не забивался и браузер успевал эти метки отрисовывать?

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

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

У этой технологии есть несколько существенных минусов
1. Очень сложная серверная часть. Попробуйте на досуге написать модуль, который генерирует вот такие картинки и их геометрические описания, и вы все поймете.

2. Абсолютная негибкость. Невозможно «приподнять» метку при наведении на нее курсора. Невозможно быстро поменять на клиенте внешний вид меток. Короче – на любой чих надо просить сервер перегенерировать картинку.

Поэтому пользователи крутились, как могли, без хотспотов – передавали наборы единичных объектов на клиент пачками, через таймаут. При этом на клиенте их снова ждали проблемы. Если вы передали на клиент 1000 точек, как их отрисовать?

Из каждой точки нужно было сгенерировать объект ymaps.Placemark и добавить его на карту. Можно было добавить метки в кластеризатор ( ymaps.Clusterer ) и добавить откластеризованные метки на карту. Тут надо обратить внимание, что при кластеризации 10 000 точек нужно сначала эти 10 000 точек инстанцировать, а потом передать в кластеризатор. То есть метка может не показаться на карте, так как войдет в кластер, но мы все равно потратим время на ее инициализацию.

Быстро и легко отрисовать на клиенте большое количество точек.
Избежать лишних инициализаций при работе с точками на клиенте.
Загружать данные на клиент строго по требованию.

Пункт 2. Рисуем метки быстро

Он умеет рисоваться на карте.
У него есть свой менеджер балуна placemark.balloon.
У него есть свой менеджер хинта placemark.hint.
У него есть редактор, который позволяет перетаскивать метку и фиксировать ее координаты placemark.editor .

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

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

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

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

После комбинации этих идей и некоторой разработки родился новый модуль API для отображения большого количества точечных объектов – ymaps.ObjectManager.

На вход этого менеджера скармливается JSON-описание объектов.
Менеджер анализирует, какие метки попадают в видимую область карты и либо рисует метки, либо кластеризует эти метки и показывает результат на карте.

Для отрисовки меток и кластеров на карте мы взяли только часть объекта ymaps.Placemark (а именно ymaps.overlay.*), которая отвечала только за отображение метки на карте. Всю инфраструктуру типа балунов и хинтов мы вынесли в единый общий компонент.

Эти приемы позволили нам неплохо продвинуться в вопросе отрисовки большого числа меток на клиенте. Вот какие мы получили приросты по скорости:

График 1. Скорость создания и добавления объектов на карту с последующей асинхронной отрисовкой их видимой части

Создание 1000 меток и добавление их на карту, все метки видны.
Создание 1000 меток и добавление их на карту с кластеризацией, все метки видны.
Создание 10000 меток и добавление их на карту с кластеризацией, все метки видны.
Создание 50 000 меток и добавление их на карту с кластеризацией, все метки видны.
Создание 50 000 меток и добавление их на карту с кластеризацией, видны 500 объектов.
Создание 50 000 меток и добавление их на карту без кластеризации, видны 10 000.

График 2. Скорость создания и добавления объектов на карту с последующей синхронной отрисовкой их видимой части

Создание 1000 меток и добавление их на карту, все метки видны.
Создание 1000 меток и добавление их на карту с кластеризацией, все метки видны.
Создание 10000 меток и добавление их на карту с кластеризацией, все метки видны.
Создание 50 000 меток и добавление их на карту с кластеризацией, все метки видны.
Создание 50 000 меток и добавление их на карту с кластеризацией, видны 500 объектов.
Создание 10 000 меток и добавление их на карту без кластеризации, видны 2000.
Создание 5000 меток и добавление их на карту без кластеризации, видны 1000.

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

У нас получилось ускорить непосредственно создание и отрисовку объектов, вдобавок к этому мы максимально оптимизировали инициализацию программных сущностей. Теперь вы можете, например, откластеризовать на клиенте 50 000 точек, и работать с картой будет комфортно.

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

Итак, мы научились быстро-быстро рисовать и кластеризовать точки на клиенте. Что дальше?

Пункт 3. Оптимально подгружаем данные

У человека на сервере много данных, он хочет показывать их на клиенте, но подгружать данные по мере надобности.
Разработчик подготавливает данные на сервере (например, реализует серверную кластеризацию) и хочет показывать на клиенте результаты этой обработки.

Для решения этих кейсов были написаны модули LoadingObjectManager и RemoteObjectManager соответственно.Оба модуля основаны по сути на реализации ObjectManager, но имеют ряд различий в алгоритме загрузки и кеширования загруженных данных.

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

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

Теперь обсудим вариант номер два – отображение на клиенте результатов серверной кластеризации. Допустим, вы написали серверную кластеризацию меток. Также вы написали скрипт, который по запросу от клиента умеет отдавать кластеры и единичные метки, не вошедшие в состав кластера.

Вам остается только создать инстанцию RemoteObjectManager и прописать в нем путь до этого чудо-скрипта. RemoteObjectManager будет работать почти так же, как и LoadingObjectManager. Разница будет только в том, что мы будем перезапрашивать данные с сервера при каждой смене зума.

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

Если с сервера передается описание метки-кластера, то на клиенте эти метки подцепят всю инфраструктуру из API – для кластеров нарисуются специальные значки, для них будут работать все стандартные поведения и так далее и тому подобное.

Пункт 4. Размышления на тему серверной реализации

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

1. Хранение информации об объектах на сервере в статических файлах

Клиентский код оперирует данными исключительно потайлово. Тайл – это некоторая нумерованная область на карте. Подробнее про нумерацию тайлов можно прочитать в нашей документации.

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

У клиентского модуля есть настройки, которые заставляют отправлять запросы за каждым новым тайлом по отдельности. Чем это ценно? Да тем, что мы получаем конечное число вариантов запроса клиента на сервер.

zoom=0, tile=[0, 0]
zoom=1, tile=[0, 0]
zoom=1, tile=[0, 1]
zoom=1, tile=[1, 0]
zoom=1, tile=[1, 1]
zoom=2, tile=[0, 0]
…

Поскольку запросы известны заранее, ответы на запросы тоже можно сгенерировать заранее. Организуем на сервере какую-то такую файловую структуру.

В файлах будет храниться примерно такой код:

При загрузке такого файла на клиенте будет вызван JSONP-callback, прописанный в файле. Данные попадут в недры LoadingObjectManager, закешируются и отрисуются в нужном виде.

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

2. Динамическое формирование ответа из статических файлов

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

3. Динамическое формирование ответа с использованием базы данных

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

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

В этом репозитории живет пример реализации серверной части с серверной grid-кластеризацией, написанный на node.js + mongo.db. может кому-то пригодится (Демо).

Заключение

Сравнительная таблица новых модулей.

Отрисовка производится только тех объектов, которые попадают в видимую область карты.

Позволяет фильтровать объекты при их отображении.

Данные загружаются для всех объектов сразу (даже для тех, которые не попадают в видимую область карты).

Сохраняет загруженные данные. Для каждого объекта данные загружаются только один раз.

Кластеризация объектов производится на стороне клиента.

При изменении коэффициента масштабирования данные загружаются заново (даже для тех объектов, для которых данные уже были загружены).

Необходимо реализовывать собственную кластеризацию.

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

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

Читайте также: