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

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

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

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

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

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

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

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

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

Подробнее о планировании маршрута с помощью токена маршрута рассказывается в статье Получение токена маршрута в Routes API и Ломаные линии перехода и токены маршрутов в Route Optimization API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. Настройте запрос Routes 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.setDestinationsWithToken. Navigation SDK получает пункты назначения и параметры маршрута из токена маршрута, поэтому вам не нужно передавать путевые точки или режим передвижения.

   setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
   setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
   

3. Проверьте статус маршрута в обратном вызове. Когда Navigation SDK завершит расчет маршрута, он передаст RouteDescription в ваш обратный вызов. Если маршрут от местоположения транспортного средства до пунктов назначения в токене маршрута найден, RouteDescription.getRouteStatus возвращает Navigator.RouteStatus.OK и вы можете запустить навигацию. Пример:

   navigator.setDestinationsWithToken(
       routeToken,
       routeDescription -> {
         if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
           navigator.startGuidance();
         }
       });
   

Проверьте, применил ли Navigation SDK ваш токен маршрута

Статус маршрута OK означает, что Navigation SDK нашел маршрут, но не обязательно тот, который вы планировали. Чтобы проверить, совпадает ли маршрут с запланированным, выполните следующие действия в обратном вызове:

1. Убедитесь, что RouteDescription.getRouteStatus возвращает Navigator.RouteStatus.OK. Navigation SDK предоставляет сведения о токене маршрута, только когда находит маршрут. Подробная информация приведена в разделе Шаг 2.

2. Вызовите метод RouteDescription.getRouteTokenExecutionDetails, чтобы получить объект RouteTokenExecutionDetails. Если сервер не предоставляет сведения о токене маршрута, этот метод возвращает null.

3. Вызовите getTokenExecutionStatus для объекта RouteTokenExecutionDetails. Если возвращается значение TOKEN_SUCCESSFULLY_APPLIED, маршрут совпадает с запланированным. Любой другой статус означает, что маршрут может отличаться от запланированного. Подробнее о значениях статуса выполнения токена…

4. Необязательно. Если статус – TOKEN_SUCCESSFULLY_APPLIED, вызовите getResolvedParameters для того же объекта RouteTokenExecutionDetails, чтобы проверить, какие параметры маршрутизации используются, например избегает ли маршрут платных дорог. Подробнее о разрешенных параметрах маршрутизации…

Значения статуса выполнения токена

Если статус маршрута – OK, вы можете начать навигацию с любым статусом выполнения токена. Статус показывает, соответствует ли маршрут запланированному.

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

Разрешенные варианты маршрутизации

getResolvedParameters возвращает объект RouteTokenResolvedParameters или null, если варианты маршрута недоступны. RouteTokenResolvedParameters имеет следующие методы:

• getTravelMode – способ передвижения, используемый на маршруте, например RoutingOptions.TravelMode.DRIVING. Navigation SDK также возвращает значение RoutingOptions.TravelMode.DRIVING, если для выбранного способа передвижения нет подходящего значения или если способ передвижения недоступен.
• getAvoidTolls – избегать ли платных дорог.
• getAvoidHighways – избегать ли автомагистралей.
• getAvoidFerries – избегать ли паромов.

Пример

В следующем примере кода показано, как спланировать маршрут с помощью токена маршрута, проверить, применил ли Navigation SDK токен, и запустить навигацию.

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

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

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

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

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

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

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

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

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

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

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

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