Мой (нано)опыт с Yandex.Maps API или зачем нужна инструкция

Introduction


Я андроид разработчик и...


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


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


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


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


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


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


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


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


Прежде чем изучить документацию, её надо найти. Искать яндекс, конечно же, будем в гугле — найдем [2] или [2].ru [3]. Мы — девелоперы, видим кнопку “для девелоперов” — жмем. Огромная иконка “Maps API” выглядит как то, что нам нужно! (It’s a trap!)


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


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


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


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


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


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


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


Class  MapKitFactory

Methods
getInstance()  - Gets the MapKit factory instance.
initialize(Context context) - Initializes the MapKit factory.
setApiKey(String apiKey) - Sets the API key to use for requests.

Спасибо, Яндекс.


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


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


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


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


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


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


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


Для решения этой задачи придется вернуться в поиск — и найти документацию для js [9]. Она кажется гораздо более подробной и объемной (я завидую). Нам необходим “HTTP geocoding request” [10] — тут довольно понятно написано, что это и как его использовать. Дело за реализацией http запросов-ответов на мобилках.


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


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


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


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


Список литературы:


[1] — https://tech.yandex.com/maps/
[2] — https://tech.yandex.com/
[3] — https://tech.yandex.ru/
[4] — https://tech.yandex.com/maps/
[5] — https://tech.yandex.com/maps/mapkit/
[6] — https://github.com/yandex/mapkit-android-demo
[7] — https://tech.yandex.com/maps/doc/mapkit/3.x/concepts/about-docpage/
[8] — https://github.com/yandex/mapkit-android-demo/tree/master/src/main/java/com/yandex/mapkitdemo
[9] — https://tech.yandex.com/maps/doc/jsapi/2.1/quick-start/index-docpage/
[10] — https://tech.yandex.com/maps/doc/geocoder/desc/concepts/input_params-docpage/

AdBlock has stolen the banner, but banners are not teeth — they will be back

More
Ads

Comments 6

    –1
    «Но, если вам, как и мне, надо очень быстро (вчера) начать использовать в вашем проекте карты, надеюсь, помогу сэкономить немного времени.» — экономия времени, это типа не связываться? тогда слишком много слов в вашей статье.
    Примеры кода по решению того или иного момента помешали привести особые моральные настройки?
      0
      экономия времени, это типа не связываться?

      Нет, связываться/не связываться — это нужно анализировать альтернативы и их плюсы и минусы. Я этого не делал, поэтому не берусь ставить крест на яндекс картах.
      Моя мысль было в том, что я потратил относительно много времени, чтобы пробраться через сайт яндекс карт, минуя неинформативные ссылки, до примеров в гитхабе, которые помогли лучше всего. И на каждом шагу я снова и снова задавался вопросом «а я точно нашел все возможное и гитхаб — это лучшее, что есть»

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

      Примеры кода по решению того или иного момента помешали привести особые моральные настройки?

      Примеры кода для чего именно? Я не исследовал внутреннюю реализацию карт, о чем сразу сообщил в статье. Для примеров кода есть гитхаб яндекса(ссылка номер 6)
      +2
      Да уж, пост как-то сильно ни о чем… Не, я понимаю огорчения автора, документация у Яндекса (да и у других в общем тоже) не всегда супер, а задачи иногда сложные. Но и вы, прямо скажем, не сильно помогли. Один простой пример:

      >Как добавить пин на карту? Ключевые слова Placemark, MapObjects. Искать в samples.
      Вообще говоря, маркеры имеют кучу разных свойств, от цвета и формы, до обработчиков событий, показывающих на карте развернутую информацию об этом объекте. Я по большей части работал в веб и с лифлетом, и в итоге примерно за год разработки добрался например до маркеров в формате SVG, с анимацией, в виде разного рода диаграмм (pie chart, к примеру). И то не могу сказать, что знаю о маркерах все. И в одном абзаце это не излагается ну никак.

      Ну то есть, я это к тому, что на самом деле на почти каждую из тем тут можно написать отдельную статью. Иногда две. Условные маршруты — вообще тема необъятная (достаточно открыть например документацию ArcGIS по этому виду API, и ужаснуться тому числу параметров, которые там имеются).
        0
        Но и вы, прямо скажем, не сильно помогли

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

        А статья имеет право на существование, потом что были те, кому статья очень сильно помогла и эти люди писали в личные сообщения благодарности и я им также благодарен за это. Позитивный фидбек поднимает настроение и желание помогать людям дальше.
        0
        А какие у них тарифы? там не всё понятно с бесплатным тарифом. Насколько я помню, в публичном месте можно бесплатно, а вот ограниченном разделе (по логину) только платно. Или не так?
          0
          К сожалению, я не смогу вам сейчас подсказать, потому то на тот момент вопрос тарифа — это было вне моей зоны ответсвенности. Также с тех пор могло многое поменяться.

        Only users with full accounts can post comments. Log in, please.