Api 2gis для android

Для работы с SDK нужно вызвать метод initialize() объекта DGis, указав контекст приложения и набор ключей доступа (объект ApiKeys).

В SDK используется два ключа: map (основной ключ SDK) и directory (ключ доступа к дополнительным API: справочнику объектов и маршрутизатору).

Дополнительно можно указать настройки журналирования (LogOptions) и настройки HTTP-клиента (HttpOptions), такие как кеширование.

Создание карты
Чтобы создать карту, добавьте MapView в ваш activity:

Для карты можно указать начальные координаты ( cameraTargetLat — широта; cameraTargetLng — долгота) и масштаб ( cameraZoom ).

MapView также можно создать программно. В таком случае настройки можно указать в виде объекта MapOptions.

Объект карты (Map) можно получить, вызвав метод getMapAsync() :

Общие принципы работы

Отложенные результаты
Некоторые методы SDK (например те, которые обращаются к удалённому серверу) возвращают отложенные результаты (Future). Для работы с ними нужно создать обработчик получения данных и обработчик ошибок.

Пример получения объекта из справочника:

По умолчанию обработка результатов происходит в UI-потоке. Чтобы это изменить, для onResult и onError можно указать Executor.

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

Потоки значений
Некоторые объекты SDK предоставляют потоки значений, которые можно обработать, используя механизм каналов: на поток можно подписаться, указав функцию-обработчик данных, и отписаться, когда обработка данных больше не требуется. Для работы с потоками значений используется интерфейс Channel.

Пример подписки на изменение видимой области карты (поток новых прямоугольных областей):

После окончания работы с каналом важно отменить подписку, чтобы избежать утечки памяти. Для этого нужно вызвать метод close() :

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

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

В общем случае работа с источниками данных выглядит следующим образом:

Чтобы удалить созданный источник данных и все связанные с ним объекты, нужно вызвать метод карты removeSource() :

Список активных источников данных можно получить, используя свойство map.sources .

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

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

Для удаления объектов используются методы removeObject() и removeObjects(). Чтобы удалить все объекты, можно использовать метод removeAll().

Маркер
Чтобы добавить маркер на карту, нужно создать объект Marker, указав нужные настройки, и передать его в вызов addObject() менеджера объектов.

В настройках нужно указать координаты маркера (параметр position ).

Чтобы изменить иконку маркера, нужно указать объект Image в качестве параметра icon . Создать Image можно с помощью следующих функций:

Чтобы изменить точку привязки иконки (выравнивание иконки относительно координат на карте), нужно указать параметр anchor.

Дополнительно можно указать текст для маркера и другие настройки (см. MarkerOptions).

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

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

Свойство-расширение .lpx преобразует целое число в объект LogicalPixel.

Многоугольник
Чтобы нарисовать на карте многоугольник, нужно создать объект Polygon, указав нужные настройки, и передать его в вызов addObject() менеджера объектов.

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

Дополнительно можно указать цвет полигона и параметры обводки (см. PolygonOptions).

Кластеризация
Для добавления маркеров на карту в режиме кластеризации нужно создать менеджер объектов (MapObjectManager) через MapObjectManager.withClustering(), указав инстанс карты, расстояние между кластерами в логических пикселях, максимальный zoom-уровень формирования кластеров и пользовательскую имплементацию протокола SimpleClusterRenderer. SimpleClusterRenderer используется для кастомизации кластеров в MapObjectManager.

Управление камерой
Для работы с камерой используется объект Camera, доступный через свойство map.camera .

Перелёт
Чтобы запустить анимацию перелёта камеры, нужно вызвать метод move() и указать параметры перелёта:

position — конечная позиция камеры (координаты и уровень приближения). Дополнительно можно указать наклон и поворот камеры (см. CameraPosition).

time — продолжительность перелёта в секундах (Duration).

animationType — тип анимации (CameraAnimationType).

Функция move() возвращает объект Future, который можно использовать, чтобы обработать событие завершения перелёта.

Для указания продолжительности перелёта можно использовать расширение .seconds :

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

Получение состояния камеры
Текущее состояние камеры (находится ли камера в полёте) можно получить, используя свойство state . См. CameraState для списка возможных состояний камеры.

Подписаться на изменения состояния камеры можно с помощью свойства stateChannel .

Получение позиции камеры
Текущую позицию камеры можно получить, используя свойство position (см. объект CameraPosition).

Подписаться на изменения позиции камеры (и угла наклона/поворота) можно с помощью свойства positionChannel .

Моё местоположение
На карту можно добавить специальный маркер, который будет отражать текущее местоположение устройства. Для этого нужно добавить на карту источник данных MyLocationMapObjectSource.

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

Пример функции, которая принимает координаты нажатия на экран и передаёт их в метод getRenderedObjects() :

Справочник объектов
Для поиска объектов в справочнике нужно создать объект SearchManager, вызвав один из следующих методов:

SearchManager.createOnlineManager() — создаёт онлайн-справочник.

SearchManager.createOfflineManager() — создаёт офлайн-справочник, работающий только с предзагруженными данными.

SearchManager.createSmartManager() — создаёт комбинированный справочник, работающий с онлайн-данными при наличии сети и с предзагруженными данными при отсутствии сети.

Если идентификатор (ID) объекта известен, то для получения информации о нём нужно вызвать метод searchById(). Метод вернёт отложенный результат DirectoryObject.

Если ID объекта не известен, то можно создать поисковый запрос (объект SearchQuery) с помощью SearchQueryBuilder и передать его в метод search(). Вызов вернёт отложенный результат SearchResult, содержащий список найденных объектов (DirectoryObject), разделенный на страницы.

Чтобы получить следующую страницу результатов поиска, нужно вызвать метод страницы fetchNextPage(), который вернёт отложенный результат Page.

Также с помощью справочника можно получать подсказки при текстовом поиске объектов (см. Suggest API для демонстрации). Для этого нужно создать объект SuggestQuery с помощью SuggestQueryBuilder и передать его в метод suggest(). Вызов вернёт отложенный результат SuggestResult, содержащий список подсказок (Suggest).

Построение маршрута
Для того, чтобы проложить маршрут на карте, нужно создать два объекта: TrafficRouter для поиска оптимального маршрута и источник данных RouteMapObjectSource для отображения маршрута на карте.

Чтобы найти маршрут между двумя точками, нужно вызвать метод findRoute(), передав координаты точек в виде объектов RouteSearchPoint. Дополнительно можно указать параметры маршрута (RouteOptions), а также список промежуточных точек маршрута (список RouteSearchPoint).

Вызов вернёт отложенный результат со списком объектов TrafficRoute. Чтобы отобразить найденный маршрут на карте, нужно на основе этих объектов создать объекты RouteMapObject и добавить их в источник данных RouteMapObjectSource.

Вместо пары TrafficRouter и RouteMapObjectSource для построения маршрута можно использовать RouteEditor и RouteEditorSource. В таком случае не нужно обрабатывать список TrafficRoute, достаточно передать координаты маршрута в виде объекта RouteParams в метод setRouteParams() и маршрут отобразится автоматически.

Собственный источник геопозиции
В рамках SDK можно использовать произвольный источник геопозиции. Для этого нужно реализовать интерфейс LocationSource.

Чтобы зарегистрировать созданный источник в SDK, нужно вызвать функцию registerPlatformLocationSource().

Основная точка входа в интерфейс — функция activate() . Когда SDK потребуется геопозиция, в эту функцию будет передан объект LocationChangeListener. После этого, чтобы сообщить текущую геопозицию, нужно передать в него массив объектов Location (от более старой позиции к более новой), используя метод onLocationChanged().

Чтобы сообщить изменение доступности источника, можно вызвать метод onAvailabilityChanged().

Дополнительно можно менять логику определения геопозиции в зависимости от требуемой точности. Требуемая точность передаётся в функцию setDesiredAccuracy() в виде объекта DesiredAccuracy.

Когда источник геопозиции больше не требуется, будет вызвана функция deactivate() .

Источник

Примеры

Создание виджета карты
Чтобы отобразить карту, для начала добавьте следующий Fragment в ваш layout-файл:

Затем инициализируйте виджет, вызвав метод setup() и передав свой ключ API. Вы также можете передать начальные координаты и требуемый масштаб. Полный список возможных параметров приведён в описании API.

Например, приведённый ниже фрагмент кода показывает карту Москвы с Кремлём в центре карты и масштабом по умолчанию:

Для вызова какой-либо функции после инициализации карты, укажите её как callback:

Добавление маркера
Вы можете добавить на карту любое количество маркеров. Чаще всего это делается через callback-функцию карты:

Из параметров вам нужно задать только координаты маркера.

Кроме того, вы можете изменить внешний вид маркера. Вы можете задать иконку в SVG-формате, размер маркера в пикселях (ширина × высота), и якорь — координаты точки, к которой привязывается маркер (X × Y, относительно левого верхнего угла). Более подробную информацию о классе MarkerOptions смотрите в описании API.

Также вы можете добавить click listener для маркера, чтобы получать события клика/касания:

Обработка событий нажатия
Чтобы получать события нажатия на карту, вы можете добавить click listener для самой карты.

Для каждого объекта на карте можно получить координаты ( event.lngLat ) и внутренний ID ( event.target.id ). Затем вы сможете использовать ID объекта, чтобы выделить его на карте (подробнее в разделе Выделение объектов). Этот же ID можно использовать для получения полной информации об объекте через другие API, например, Places API, так как ID объектов одинаковы для всех API.

Выделение объектов
Вы можете выделять на карте объекты: здания, дороги и т. д.

Для этого вызовите метод mapObjectsByIds(), передав ему список ID объектов, а затем вызовите метод setSelectedObjects() по результату mapObjectsByIds(). Вы можете получить нужные ID, добавив для карты click listener (смотрите раздел Обработка событий нажатия).

Чтобы изменить список выделенных объектов, вызовите этот метод еще раз, передав в него новый список ID.

Чтобы убрать все выделения с карты, передайте пустой список методу setSelectedObjects().

Источник

2GIS API 2.0

Мы рассказали про новый 2ГИС почти всё. Точнее, почти обо всём, с чем сталкивается пользователь. Настало время рассказать о том, что у него “под капотом”. Угадали, речь об API 2ГИС.

Если вы пользовались новым 2ГИС с момента его появления, вы уже видели 2GIS API 2.0 в деле. Сегодня же он вышел из статуса беты и стал доступен всем желающим. Отдельно хотим поблагодарить тех, кто участвовал в тестировании: ребята, спасибо, вы помогли сделать продукт именно таким, каким он получился. То есть более, чем неплохим.

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

Что внутри?

API 2.0 основан на open-source библиотеке Leaflet. Она проста, быстра и активно развивается. Количество кода заметно сократилось, без какого-либо ущерба для функциональности.

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

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

Также в API 2.0 появились новые базовые функции, которые отсутствовали в первой версии — от возможности указать HTML-код вместо картинки маркера и до чтения данных в формате GeoJSON.

Дизайн

Внешний вид продукта для нас важен не менее точности и полноты информации. А она очень для нас важна.

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

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

Выбор темы оформления осуществляется на этапе подключения API при помощи параметра skin:

Модульность

Бывает, что для решения задачи все функции API не требуются. Поэтому мы сделали новый API модульным. Мы предлагаем два готовых пакета — full и basic.

Пакет basic содержит в себе базовые функции:

— карта;
— маркеры;
— балуны;
— растровые слои;
— GeoJSON-слой;
— геометрии;
— группы;
— контрол полноэкранного режима;
— масштабная линейка.

Пакет full дополнительно включает в себя:

— подсказки;
— линейку измерения расстояний;
— контрол геолокации;
— функцию для работы с Ajax;
— класс для работы с WKT-форматом;
— геокликер.

Но если вам нужен уникальный набор функций, вы можете сделать сборку под свои нужды.

А еще, кроме модулей из предустановленных пакетов, вы можете подключить любой внешний модуль библиотеки Leaflet, например, Кластеризатор или Heatmap. Или вообще разработать собственный модуль, который покроет ваши специфические потребности.

Легче, проще, быстрее

Весь JS- и CSS-код новой версии API в два раза меньше, чем у старой. Это кардинально ускорило загрузку страниц с картой:

Загрузчик (КБ)	JavaScript-код (КБ)	CSS-код (КБ)
API 1.0	1.9	671	59.0
API 2.0 (пакет Full)	2.4	377	44.9
API 2.0 (пакет Basic)	2.4	214	24.9

Данные приведены для браузера Google Chrome. CSS-код API карт 2.0 также включает в себя изображения, закодированные в base64.

Поддержка устройств и браузеров

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

Полноэкранный режим, который особенно полезен на небольших экранах, работает с использованием fullscreen API (в тех браузерах, где это возможно). А позиции элементов управления подстраиваются под тип устройства, чтобы на них было удобно нажимать:

Геокликер и входы в здания

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

Дальше, можно посмотреть подробную информацию о каждой из них:

Но мы пошли еще дальше. Теперь 2ГИС помогает пользователю не просто найти организацию, но и попасть в нее. Наши сотрудники обошли более 1 млн компаний и узнали, где находятся входы в них. Даже такие:

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

Открытость

2ГИС поддерживает движение Open Source. Разработчикам должен прийтись по вкусу факт, что мы открыли исходный код API карт. Это значит, что любой может легко изучить его и разработать собственный модуль.

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

Качество данных

Здесь ничего не изменилось — мы по прежнему держим планку качества на высшем уровне. На карте 2ГИС вы найдете не только все здания, но и парки, улицы, фонтаны, заборы, гаражи и странные сооружения, которые есть в любом городе.

Источник

Api 2gis для android