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 ou de l'API Route Optimization peut vous aider à spécifier deux éléments pour votre 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 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 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 ou l'API Route Optimization renvoie un jeton d'itinéraire chiffré qui inclut la polyligne 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 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 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 pour qu'elle réponde aux exigences d'utilisation d'un jeton d'itinéraire :

   • 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 :

   String 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 Navigator.setDestinationsWithToken. Le SDK Navigation obtient les destinations et les options de calcul d'itinéraire à partir du jeton de route. Vous n'avez donc pas besoin de transmettre de points de cheminement ni de mode de transport.

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

3. Vérifiez l'état de la route dans votre rappel. Une fois que le SDK Navigation a terminé de calculer l'itinéraire, il transmet un RouteDescription à votre rappel. S'il trouve un itinéraire entre l'emplacement du véhicule et les destinations de votre jeton d'itinéraire, RouteDescription.getRouteStatus renvoie Navigator.RouteStatus.OK et vous pouvez démarrer le guidage. Exemple :

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

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 rappel :

1. Vérifiez que RouteDescription.getRouteStatus renvoie Navigator.RouteStatus.OK. Le SDK Navigation ne fournit des détails sur le jeton de route que lorsqu'il trouve une route. Pour en savoir plus, consultez l'étape 2.

2. Appelez RouteDescription.getRouteTokenExecutionDetails pour obtenir un objet RouteTokenExecutionDetails. Si le serveur ne fournit pas d'informations sur le jeton de route, cette méthode renvoie null.

3. Appelez getTokenExecutionStatus sur l'objet RouteTokenExecutionDetails. Si elle renvoie TOKEN_SUCCESSFULLY_APPLIED, l'itinéraire correspond à l'itinéraire prévu. Tout autre état signifie que l'itinéraire peut différer de l'itinéraire prévu. Pour en savoir plus sur chaque état, consultez Valeurs d'état d'exécution des jetons.

4. Facultatif : Si l'état est TOKEN_SUCCESSFULLY_APPLIED, appelez getResolvedParameters sur le même objet RouteTokenExecutionDetails pour vérifier les options de routage utilisées par l'itinéraire, 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 l'état de l'itinéraire est OK, vous pouvez démarrer le guidage, quel que soit l'é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

getResolvedParameters renvoie un objet RouteTokenResolvedParameters ou null si les options de routage ne sont pas disponibles. RouteTokenResolvedParameters comporte les méthodes suivantes :

• getTravelMode : mode de transport utilisé par l'itinéraire, par exemple RoutingOptions.TravelMode.DRIVING. Le SDK Navigation indique également RoutingOptions.TravelMode.DRIVING lorsque l'itinéraire utilise un mode de transport qui n'a pas de valeur correspondante ou lorsque le mode de transport n'est pas disponible.
• getAvoidTolls : indique si l'itinéraire évite les péages.
• getAvoidHighways : indique si l'itinéraire évite les autoroutes.
• getAvoidFerries : indique si l'itinéraire évite les ferries.

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.

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);

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 :

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • 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.