Построй маршрут

Примечание. Изменения в том, как Navigation SDK следует запланированным маршрутам, внедряются постепенно и станут доступны для всех проектов к 22 октября 2026 г. До этого момента Routes API может отклонять запросы, содержащие betterRouteTimeTolerance.

Иногда вам может потребоваться спланировать маршрут, который ваше приложение предоставляет пользователям. Используя токен маршрута из Routes API, Routes Preferred API или Route Optimization API, вы можете указать две вещи для запланированного маршрута:

• Ломаная линия для маршрута.

• Цели маршрута

Вот несколько примеров целей маршрутизации:

• Минимизация времени доставки. Например, компания, доставляющая еду, может стремиться минимизировать время доставки.

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

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

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

Важно! Маршрут, по которому едет водитель, может отличаться от запланированного. Маршрут может измениться во время поездки из-за изменения дорожных условий, съезда с запланированного маршрута или переключения на более быстрый маршрут. При расчете нового маршрута Navigation SDK использует параметры, заданные в токене маршрута, например избегать платных дорог.

Дополнительную информацию о планировании маршрута с помощью токена маршрута можно найти в разделе Получение токена маршрута в Routes API и Переходные ломаные линии и токены маршрутов в Route Optimization API.

Зачем использовать токен маршрута для целей маршрута

Токен маршрута из Routes API, Routes Preferred API или Route Optimization API позволяет лучше контролировать маршрут:

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

• Выбор лучшего маршрута для Navigation SDK Если вы запрашиваете токены маршрутов при создании маршрутов в Routes API, вы получаете токен для каждого созданного маршрута. Затем вы можете выбрать токен для маршрута, который хотите использовать, и передать его в Navigation SDK.

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

• Указывать более сложные цели маршрута, например экологичный или кратчайший маршрут.

Примечание. Токен маршрута предназначен для одного конкретного пункта отправления и пункта назначения в определенное время. Чтобы получить новый токен, необходимо отправить новый запрос к Routes API, Routes Preferred API или Route Optimization API.

Как работают токены маршрутов

Для планирования маршрута с учетом целей можно использовать Routes API, Routes Preferred API или Route Optimization API. Вы можете передать токен маршрута, возвращенный любым из этих API, в Navigation SDK, чтобы указать, как он должен прокладывать маршрут для вашего транспортного средства.

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

1. Routes API, Routes Preferred API или Route Optimization API возвращает зашифрованный токен маршрута, который включает ломаную линию маршрута и цели маршрута.

2. Вы передаете токен маршрута в Navigation SDK.

3. Navigation SDK запускает навигацию по запланированному маршруту, даже если доступен более быстрый маршрут.

4. Если во время поездки меняются условия дорожного движения или автомобиль съезжает с запланированного маршрута, Navigation SDK рассчитывает новый маршрут, соответствующий целям и параметрам, заданным в токене маршрута.

Это позволяет максимально приблизить фактический маршрут к запланированному.

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

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

• Транспортное средство начинает движение не из запланированной начальной точки.
• Дорожные условия или ситуация на дорогах изменились во время поездки.
• Транспортное средство отклоняется от запланированного маршрута.

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

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

Как спланировать маршрут с помощью токена маршрута

Чтобы спланировать маршрут, создайте токен маршрута и передайте его в Navigation SDK, как описано ниже.

Шаг 1. Создайте токен маршрута с помощью Routes API, Routes Preferred API или Route Optimization API

1. Запросите токен маршрута одним из следующих способов:

   • Routes API: computeRoutes. Подробнее о том, как запросить токен маршрута в Routes API, рассказывается в статьях Расчет маршрута и Получение токена маршрута.

   • Routes Preferred API: computeCustomRoutes. Подробнее о том, как запросить токен маршрута в Routes Preferred API…

   • Route Optimization API: optimizeTours или batchOptimizeTours. Подробнее о том, как запросить токен маршрута в Route Optimization API, рассказывается в статье Ломаные линии переходов и токены маршрутов.

2. Настройте запрос Routes API или Routes Preferred API в соответствии с требованиями для использования токена маршрута:

   • Присвойте travelMode значение DRIVE или TWO_WHEELER.
   • Присвойте routingPreference значение TRAFFIC_AWARE или TRAFFIC_AWARE_OPTIMAL.
   • Не используйте путевые точки Via.

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

Шаг 2. Передайте токен маршрута в Navigation SDK

1. Сохраните токен маршрута. В Navigation SDK настройте строку для хранения токена маршрута. Пример:

   String routeToken = "route token returned by Routes API";

   Пример возвращенного токена маршрута:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Передайте токен маршрута в Navigation SDK с помощью метода Navigator.setDestinations, указав те же путевые точки, которые вы использовали при создании токена маршрута:

   setDestinations(List destinations, CustomRoutesOptions customRoutesOptions, DisplayOptions displayOptions);

   Пример:

   CustomRoutesOptions customRoutesOptions =
         CustomRoutesOptions.builder()
         .setRouteToken(routeToken)
         .setTravelMode(TravelMode.DRIVING)
         .build();

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

Метод Navigator.setDestinations возвращает статус запроса. Если маршрут от местоположения автомобиля до указанного пункта назначения найден, возвращается RouteStatus.OK.

Подробнее об этом методе рассказывается в статье Navigator.setDestinations.

Пример

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

    ArrayList <Waypoint> destinations = Lists.newArrayList();
    Waypoint waypoint1 =
       Waypoint.builder()
          .setLatLng(10, 20)
          .setTitle("title")
          .setVehicleStopover(true)
          .build();
    destinations.add(waypoint1);
    Waypoint waypoint2 =
       Waypoint.builder()
          .setPlaceId("ChIJYV-J-ziuEmsRIMyoFaMedU4")
          .setTitle("title")
          .setVehicleStopover(true)
           .build();
    destinations.add(waypoint2);

    String routeToken = "route token returned by Routes API";

    CustomRoutesOptions customRoutesOptions =
       CustomRoutesOptions.builder()
          .setRouteToken(routeToken)
          .setTravelMode(TravelMode.DRIVING)
          .build();

    // Existing flow to get a Navigator.
    NavigationApi.getNavigator(...);

    // Existing flow for requesting routes.
    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions);

    // Or with display options.
    DisplayOptions displayOptions = new DisplayOptions();

    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions, displayOptions);

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

Как взаимодействуют токены маршрутов и Navigation SDK

Вот как Navigation SDK обрабатывает запланированный маршрут:

• Переопределяет все ранее заданные целевые страницы.

• Использует начальное местоположение автомобиля.

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

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

  • RoutingOptions.avoidHighways()
  • RoutingOptions.avoidTolls()
  • RoutingOptions.avoidFerries()
  • Navigator.setLicensePlateRestrictionInfo()
  • режим передвижения, заданный в приложении;

• Учитывает эти настройки при расчете или корректировке маршрута:

  • Цели маршрута из токена маршрута, например экологичный или кратчайший маршрут. Если Navigation SDK нужно скорректировать маршрут, он использует цели маршрута, которые вы указали при запросе токена маршрута.

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