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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете использовать 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, и учитывать возможные изменения, чтобы избежать негативного влияния на бизнес.

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

Вы можете спланировать маршрут, создав токен маршрута и передав его в 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 настройте строку для хранения токена маршрута. Пример:

   let routeToken = "route token returned by Routes API"
   

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

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

2. Передайте токен маршрута в Navigation SDK с помощью метода setDestinationsWithToken:completionHandler: класса mapView.navigator. Navigation SDK получает пункты назначения и параметры маршрута из токена маршрута, поэтому вам не нужно передавать путевые точки.

   Режим поездки, заданный в приложении, например mapView.travelMode, должен иметь одно из следующих значений:

   • .driving (GMSNavigationTravelModeDriving): на автомобиле. Это значение по умолчанию, поэтому в большинстве приложений его не нужно менять.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): на мотоцикле.

   При указании любого другого способа передвижения запрос завершится ошибкой .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). При указании любого из допустимых значений в маршруте будет использоваться способ передвижения, указанный в токене маршрута. Например, если в вашем приложении используется режим вождения, а токен маршрута предназначен для двухколесного транспортного средства, Navigation SDK предоставит маршрут для двухколесного транспортного средства. Чтобы узнать, какой способ передвижения используется на маршруте, проверьте resolvedParameters.travelMode. Подробнее о разрешенных параметрах маршрутизации…

   Примечание. Если в вашем приложении используется версия Navigation SDK ниже 11.3, используйте устаревший метод setDestinations:routeToken:callback: и передайте те же путевые точки, которые вы использовали для создания токена маршрута.

3. Проверьте статус маршрута в обработчике завершения. Когда Navigation SDK завершает расчет маршрута, он передает GMSNavigationRouteDescription обработчику завершения. Если маршрут от местоположения транспортного средства до пунктов назначения в токене маршрута найден, то в описании маршрута routeStatus будет .OK (GMSRouteStatusOK) и вы сможете запустить навигацию. В противном случае обработчик завершения также получит NSError с описанием ошибки. Пример:

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

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

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

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

1. Убедитесь, что в описании маршрута в поле routeStatus указано значение .OK. Navigation SDK предоставляет сведения о токене маршрута, только когда находит маршрут. Подробнее о шаге 2…

2. Получите описание маршрута routeTokenExecutionDetails – объект, соответствующий протоколу GMSNavigationRouteTokenExecutionDetails. Если сервер не предоставляет сведения о токене маршрута, это свойство имеет значение nil.

3. Проверьте свойство tokenExecutionStatus в сведениях о выполнении. Если он .tokenSuccessfullyApplied, то маршрут совпадает с запланированным. Любой другой статус означает, что маршрут может отличаться от запланированного. Подробную информацию о каждом статусе можно найти в разделе Значения статуса выполнения токена.

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

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

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

Статус	следовать по запланированному маршруту;	Описание
.tokenSuccessfullyApplied	Да	Navigation SDK применил токен маршрута.
.tokenAppliedWithLocationMismatch	Необязательно	Navigation SDK не удалось перестроить запланированный маршрут, и устройство находилось на расстоянии более 25 метров от начальной точки в токене маршрута. Маршрут по-прежнему использует пункты назначения и параметры маршрутизации из вашего токена маршрута.
.tokenIgnoredOther	Необязательно	Navigation SDK не удалось перестроить запланированный маршрут по другой причине, например из-за того, что дорога на запланированном маршруте закрыта. Маршрут по-прежнему использует пункты назначения и параметры маршрутизации из вашего токена маршрута.
.noTokenProvided	Неприменимо	Запрос маршрута не содержал токен маршрута.
.unknown	Неизвестно	Статус неизвестен.

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

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

resolvedParameters – объект, соответствующий протоколу GMSNavigationRouteTokenResolvedParameters, или nil, если варианты маршрутов недоступны. У него есть следующие свойства:

• travelMode – способ передвижения, используемый на маршруте, например .driving (GMSNavigationTravelModeDriving). Navigation SDK также сообщает .driving, когда на маршруте используется способ передвижения, для которого нет соответствующего значения, или когда способ передвижения недоступен.
• avoidTolls – избегать ли платных дорог.
• avoidHighways – избегать ли автомагистралей.
• avoidFerries – избегать ли паромов.
• avoidTunnels – указывает, был ли маршрут рассчитан так, чтобы по возможности избегать туннелей.
• avoidVignettes – страны, в которых маршрут был рассчитан так, чтобы по возможности избегать платных дорог, для которых требуется виньетка. Указываются в виде двухбуквенных кодов регионов Unicode CLDR, например CH для Швейцарии.
• rerouteStrategy – стратегия, которую серверная часть маршрутизации использует для расчета новых маршрутов во время поездки. Стратегии включают .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), которая использует параметры маршрутизации в токене маршрута для расчета новых маршрутов.

Если статус выполнения токена не .tokenSuccessfullyApplied, Navigation SDK сообщает только travelMode, avoidTolls, avoidHighways и avoidFerries. Остальные свойства имеют значения по умолчанию, даже если вы запрашивали маршрут без туннелей или платных дорог: avoidTunnels – false (NO), avoidVignettes – пустое значение, а rerouteStrategy – .unknown (GMSNavigationRerouteStrategyUnknown).

Пример

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

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

Сценарии с несколькими остановками

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

Navigation SDK не переходит к следующему пункту назначения автоматически. Когда транспортное средство прибывает в путевую точку, вызовите continueToNextDestinationWithCompletion:, чтобы начать следующий этап поездки. Это также относится к токенам маршрутов с промежуточными путевыми точками. Когда вы переходите к следующему пункту назначения, Navigation SDK продолжает следовать маршруту из вашего токена маршрута, а не планирует новый маршрут.

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

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

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

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

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

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

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

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • режим передвижения, заданный в приложении;

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

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

Примечание. При использовании setDestinationsWithToken:completionHandler: вы не передаете путевые точки, поэтому Navigation SDK использует пункты назначения и параметры путевых точек из токена маршрута. Чтобы задать параметры путевых точек, например предпочтительную сторону дороги или остановки, используйте поля sideOfRoad и vehicleStopover в путевых точках в запросе к Routes API. Начальной точкой всегда является местоположение устройства, поэтому параметры, заданные для начальной точки в запросе к Routes API, не применяются.