Planifier un itinéraire

Vous pouvez parfois vouloir planifier l'itinéraire que votre application fournit aux utilisateurs. L'utilisation d'un jeton de route de l'API Routes, de l'API Routes Preferred ou de l'API Route Optimization peut vous aider à spécifier deux éléments pour l'itinéraire planifié :

• Une polyligne pour l'itinéraire

• Vos objectifs d'itinéraire

Voici quelques exemples d'objectifs de routage :

• Réduire le délai de livraison : une entreprise de livraison de repas peut vouloir réduire le temps nécessaire à la livraison des repas.

• Réduire le temps de trajet ou la consommation de carburant : une entreprise de logistique peut vouloir améliorer l'efficacité de ses conducteurs et réduire ses coûts de carburant.

• Réduire le temps de trajet : une opération de répartition de service peut vouloir réduire le temps nécessaire pour que les opérateurs accèdent à une demande de tâche.

• Réduire les coûts et améliorer la sécurité : une entreprise de covoiturage peut vouloir trouver un itinéraire moins coûteux pour les passagers et éviter certaines zones pour des raisons de sécurité.

Pour en savoir plus sur la planification d'un itinéraire à l'aide d'un jeton de route, consultez Obtenir un jeton de route dans l'API Routes et Transition des polylignes et des jetons de route dans l'API Route Optimization.

Pourquoi utiliser un jeton de route pour les objectifs de route ?

Avec un jeton de route de l'API Routes, de l'API Routes Preferred ou de l'API Route Optimization, vous contrôlez mieux l'itinéraire fourni :

• Planifiez un itinéraire à l'avance pour que le SDK Navigation l'utilise.

• Choisissez le meilleur itinéraire à utiliser pour le SDK Navigation. Si vous demandez des jetons de route lors de la génération de routes dans l'API Routes, vous obtenez un jeton de route pour chaque route générée. Vous pouvez ensuite choisir le jeton de l'itinéraire que vous souhaitez utiliser lorsque vous le transmettez au SDK Navigation.

• Estimez le prix à l'avance, y compris les estimations de l'heure d'arrivée prévue et de la distance. Bien que le coût et la durée réels puissent varier, cette estimation réduit l'écart entre le coût prévu et le coût réel de l'itinéraire.

• Spécifiez des objectifs d'itinéraire plus avancés, tels que l'itinéraire écologique ou l'itinéraire le plus court.

Fonctionnement des jetons de route

Vous pouvez utiliser l'API Routes, l'API Routes Preferred ou l'API Route Optimization pour planifier un itinéraire à l'aide d'objectifs d'itinéraire. Vous pouvez transmettre un jeton de route renvoyé par l'une de ces API au SDK Navigation pour guider l'itinéraire de votre véhicule.

Voici ce qui se passe lorsque vous demandez et utilisez un jeton d'itinéraire :

1. L'API Routes, l'API Routes Preferred ou l'API Route Optimization renvoie un jeton de route chiffré qui inclut la polyligne de l'itinéraire et les objectifs de l'itinéraire.

2. Vous transmettez le jeton de route au SDK Navigation.

3. Le SDK Navigation démarre la navigation sur l'itinéraire prévu, même si un itinéraire plus rapide est disponible.

4. Pendant le trajet, si les conditions de circulation ou de route changent, ou si le véhicule quitte l'itinéraire prévu, le SDK Navigation calcule un nouvel itinéraire qui respecte les objectifs et les options de routage définis dans votre jeton d'itinéraire.

Ce processus permet de maximiser la proximité entre l'itinéraire réel et l'itinéraire planifié.

Pourquoi un itinéraire planifié peut ne pas être suivi exactement

La navigation commence sur l'itinéraire planifié, mais l'itinéraire réel peut en différer dans les situations suivantes :

• Le véhicule démarre loin du point de départ prévu.
• Les conditions de circulation ou de l'état de la route changent pendant le trajet.
• Le véhicule quitte l'itinéraire prévu.

Ces différences peuvent affecter la distance, l'heure d'arrivée prévue et d'autres caractéristiques importantes du trajet que vous avez planifié.

Planifier un itinéraire à l'aide d'un jeton d'itinéraire

Vous pouvez planifier un itinéraire en créant un jeton d'itinéraire, puis en le transmettant au SDK Navigation, comme décrit dans les étapes suivantes :

Étape 1 : Créez un jeton de route à l'aide de l'API Routes, de l'API Routes Preferred ou de l'API Route Optimization

1. Demandez un jeton d'itinéraire à l'aide de l'une des méthodes suivantes :

   • API Routes : computeRoutes. Pour en savoir plus sur la demande d'un jeton d'itinéraire dans l'API Routes, consultez Calculer un itinéraire et Obtenir un jeton d'itinéraire.

   • API Routes Preferred : computeCustomRoutes. Pour en savoir plus sur la demande d'un jeton de route dans l'API Routes Preferred, consultez Planifier un itinéraire.

   • API Route Optimization : optimizeTours ou batchOptimizeTours. Pour en savoir plus sur la demande d'un jeton d'itinéraire dans l'API Route Optimization, consultez Polylignes de transition et jetons d'itinéraire.

2. Configurez votre requête API Routes ou API Routes Preferred pour répondre aux exigences d'utilisation d'un jeton de route :

   • Définissez travelMode sur DRIVE ou TWO_WHEELER.
   • Définissez routingPreference sur TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
   • N'utilisez pas de points de cheminement Via.

Étape 2 : Transmettez le jeton d'itinéraire au SDK Navigation

1. Stocker le jeton de route : dans le SDK Navigation, configurez une chaîne pour stocker le jeton de route. Exemple :

   let routeToken = "route token returned by Routes API"
   

   Exemple de jeton d'itinéraire renvoyé :

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

2. Transmettez le jeton d'itinéraire au SDK Navigation à l'aide de la méthode setDestinationsWithToken:completionHandler: de mapView.navigator. Le SDK Navigation obtient les destinations et les options de routage à partir du jeton de route. Vous n'avez donc pas besoin de transmettre de points de cheminement.

   Le mode de transport défini dans votre application, par exemple mapView.travelMode, doit correspondre à l'une des valeurs suivantes :

   • .driving (GMSNavigationTravelModeDriving) : en voiture. Il s'agit de la valeur par défaut. La plupart des applications n'ont donc pas besoin de la modifier.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler) : deux-roues.

   Tout autre mode de transport entraîne l'échec de la requête avec .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). Avec l'une ou l'autre des valeurs acceptées, l'itinéraire utilise le mode de transport de votre jeton d'itinéraire. Par exemple, si votre application utilise la conduite et que votre jeton de route est destiné à un itinéraire en deux-roues, le SDK Navigation fournit un itinéraire en deux-roues. Pour confirmer le mode de transport utilisé par l'itinéraire, vérifiez resolvedParameters.travelMode. Pour en savoir plus, consultez Options de routage résolues.

3. Vérifiez l'état de l'itinéraire dans votre gestionnaire d'achèvement. Lorsque le SDK Navigation a terminé de calculer l'itinéraire, il transmet un GMSNavigationRouteDescription à votre gestionnaire d'achèvement. S'il trouve un itinéraire entre la position du véhicule et les destinations de votre jeton d'itinéraire, le routeStatus de la description de l'itinéraire est .OK (GMSRouteStatusOK), et vous pouvez démarrer le guidage. Sinon, votre gestionnaire d'achèvement reçoit également un NSError qui décrit l'échec. Exemple :

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

Vérifier si le SDK Navigation a appliqué votre jeton d'itinéraire

L'état d'itinéraire .OK signifie que le SDK Navigation a trouvé un itinéraire, mais pas nécessairement celui que vous aviez prévu. Pour vérifier si l'itinéraire correspond à celui que vous avez planifié, procédez comme suit dans votre gestionnaire d'achèvement :

1. Vérifiez que la valeur de routeStatus dans la description de la route est .OK. Le SDK Navigation ne fournit des détails sur le jeton d'itinéraire que lorsqu'il trouve un itinéraire. Pour en savoir plus, consultez l'étape 2.

2. Obtenez l'objet routeTokenExecutionDetails de la description de l'itinéraire, qui est conforme au protocole GMSNavigationRouteTokenExecutionDetails. Si le serveur ne fournit pas d'informations sur le jeton de route, cette propriété est nil.

3. Vérifiez la propriété tokenExecutionStatus des détails de l'exécution. Si la valeur est .tokenSuccessfullyApplied, l'itinéraire correspond à celui que vous avez planifié. Tout autre état signifie que l'itinéraire peut différer de celui que vous avez planifié. Pour en savoir plus sur chaque état, consultez Valeurs d'état d'exécution des jetons.

4. Facultatif : Si l'état est .tokenSuccessfullyApplied, vérifiez la propriété resolvedParameters des mêmes détails d'exécution pour voir quelles options d'itinéraire l'itinéraire utilise, par exemple s'il évite les péages. Pour en savoir plus, consultez Options de routage résolues.

Valeurs d'état d'exécution du jeton

Si routeStatus est défini sur .OK, vous pouvez démarrer le guidage avec n'importe quel état d'exécution du jeton. L'état vous indique si l'itinéraire suit votre itinéraire prévu.

Si l'itinéraire ne suit pas nécessairement l'itinéraire planifié et que l'itinéraire exact est important (par exemple, parce que vous l'avez utilisé pour calculer un prix), consignez l'état ou demandez un nouveau jeton d'itinéraire à partir de la position actuelle du véhicule.

Options de routage résolues

resolvedParameters est un objet conforme au protocole GMSNavigationRouteTokenResolvedParameters, ou nil si les options de routage ne sont pas disponibles. Il possède les propriétés suivantes :

• travelMode : mode de transport utilisé par l'itinéraire, par exemple .driving (GMSNavigationTravelModeDriving). Le SDK Navigation indique également .driving lorsque l'itinéraire utilise un mode de transport sans valeur correspondante ou lorsque le mode de transport n'est pas disponible.
• avoidTolls : indique si l'itinéraire évite les péages.
• avoidHighways : indique si l'itinéraire évite les autoroutes.
• avoidFerries : indique si l'itinéraire évite les ferries.
• avoidTunnels : indique si l'itinéraire a été calculé pour éviter les tunnels dans la mesure du possible.
• avoidVignettes : pays dans lesquels l'itinéraire a été calculé pour éviter les vignettes de péage lorsque cela est possible, sous forme de codes de région CLDR Unicode à deux lettres, par exemple CH pour la Suisse.
• rerouteStrategy : stratégie utilisée par le backend de routage pour calculer de nouveaux itinéraires pendant le trajet. Les stratégies incluent .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), qui utilise les paramètres de routage de votre jeton de route pour calculer de nouveaux itinéraires.

Si l'état d'exécution du jeton n'est pas .tokenSuccessfullyApplied, le SDK Navigation ne signale que travelMode, avoidTolls, avoidHighways et avoidFerries. Les autres propriétés ont leurs valeurs par défaut, même si vous avez demandé d'éviter les tunnels ou les vignettes de péage lorsque vous avez demandé le jeton de route : avoidTunnels est false (NO), avoidVignettes est vide et rerouteStrategy est .unknown (GMSNavigationRerouteStrategyUnknown).

Exemple

L'exemple de code suivant montre comment planifier un itinéraire à l'aide d'un jeton d'itinéraire, vérifier si le SDK Navigation a appliqué le jeton et démarrer le guidage.

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
}

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;
}];

Scénarios avec plusieurs arrêts

Vous pouvez configurer jusqu'à 25 points de cheminement.

Le SDK Navigation ne passe pas automatiquement à la destination suivante. Lorsque le véhicule arrive à un point de cheminement, appelez continueToNextDestinationWithCompletion: pour démarrer l'étape suivante du trajet. Cela s'applique également aux jetons de route comportant des points de cheminement intermédiaires. Lorsque vous passez à la destination suivante, le SDK Navigation continue de suivre l'itinéraire de votre jeton d'itinéraire au lieu de planifier un nouvel itinéraire.

Interaction entre les jetons de route et le SDK Navigation

Voici comment le SDK Navigation gère votre itinéraire planifié :

• Remplace toutes les destinations précédemment définies.

• Utilise la position de départ du véhicule.

• Ajuste l'itinéraire en fonction des conditions de circulation et de l'état de la route. Consultez Pourquoi un itinéraire planifié peut ne pas être suivi exactement.

• Utilise les options de routage définies dans votre jeton de route au lieu des paramètres suivants dans votre application, y compris lorsqu'il calcule un nouvel itinéraire pendant le trajet :

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • Le mode de transport défini dans votre application

• suit ces paramètres lorsqu'il calcule ou ajuste l'itinéraire :

  • Objectifs d'itinéraire à partir de votre jeton d'itinéraire, tels que l'itinéraire écologique ou l'itinéraire le plus court. Si le SDK Navigation doit ajuster l'itinéraire, il utilise les objectifs d'itinéraire que vous avez spécifiés lorsque vous avez demandé le jeton d'itinéraire.
  • Options liées aux points de cheminement de votre jeton d'itinéraire, telles que la préférence de côté de la route.