Planifier un itinéraire

Il peut arriver que vous souhaitiez planifier l'itinéraire que votre application fournit aux utilisateurs. L'utilisation d'un jeton d'itinéraire de l'API Routes, de l'API Routes Preferred 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 que vous pouvez avoir :

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

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

• Réduire le temps de trajet jusqu'à la destination : une opération de répartition de services peut vouloir réduire le temps nécessaire pour que les opérateurs répondent à une demande de travail.

• 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é.

Important: L'itinéraire réel peut différer de l'itinéraire planifié fourni par le jeton. Les changements de trafic, les conditions routières ou le véhicule qui s'écarte de l'itinéraire donné peuvent entraîner des modifications de l'itinéraire. Lorsque des modifications se produisent, le SDK Navigation tente en permanence de revenir à l'itinéraire planifié ou, si cela n'est pas possible, suit les objectifs d'itinéraire dans le jeton d'itinéraire.

Pour en savoir plus sur la planification d'un itinéraire à l'aide d'un jeton d'itinéraire, consultez Demander un jeton d'itinéraire dans l'API Routes et Polylignes de transition et jetons d'itinéraire dans l'API Route Optimization.

Pourquoi utiliser un jeton d'itinéraire pour les objectifs d'itinéraire ?

Avec un jeton d'itinéraire de l'API Routes, de l'API Routes Preferred ou de l'API Route Optimization, vous avez plus de contrôle sur l'itinéraire fourni :

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

• Choisissez le meilleur itinéraire à utiliser pour le SDK Navigation. Si vous demandez des jetons d'itinéraire lorsque vous générez des itinéraires dans l'API Routes, vous obtenez un jeton d'itinéraire pour chaque itinéraire généré. 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 le temps 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.

Conseil : Un jeton d'itinéraire est destiné à une origine et à une destination spécifiques, et à un moment donné. Vous devez effectuer une nouvelle requête d'API Routes, d'API Routes Preferred ou d'API Route Optimization pour obtenir un nouveau jeton d'itinéraire.

Fonctionnement des jetons d'itinéraire

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 d'itinéraire renvoyé par l'une de ces API au SDK Navigation pour guider le routage 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 d'itinéraire chiffré qui inclut la polyligne de l'itinéraire et les objectifs d'itinéraire.

2. Vous transmettez le jeton d'itinéraire au SDK Navigation.

3. Le SDK Navigation récupère l'itinéraire ou, si l'itinéraire n'est pas disponible en raison de conditions changeantes, il récupère l'itinéraire le plus adapté.

4. Pendant le trajet, si le trafic ou d'autres conditions routières changent, ou si un véhicule s'écarte de l'itinéraire planifié, les itinéraires modifiés tentent en permanence de correspondre au meilleur itinéraire en fonction des objectifs d'itinéraire du jeton.

Ce processus maximise la proximité de l'itinéraire réel avec votre itinéraire planifié.

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

Considérez votre itinéraire planifié et vos objectifs d'itinéraire comme des consignes à suivre : ils ne sont pas prescriptifs. Vous pouvez constater une différence entre votre itinéraire planifié et l'itinéraire fourni par la navigation guidée en raison de différences dans les conditions routières, le lieu de départ ou d'autres paramètres qui ont changé depuis que vous avez créé l'itinéraire planifié. Cette différence peut entraîner une inadéquation entre vos objectifs planifiés et réels en termes de distance et d'heure d'arrivée prévue, entre autres qualités importantes du trajet.

Conseil : Nous vous recommandons de toujours demander un nouveau jeton d'itinéraire chaque fois que vous définissez la destination dans le SDK Navigation, et de prévoir une certaine variation pour éviter tout impact sur votre entreprise.

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éer un jeton d'itinéraire à l'aide de l'API Routes, de l'API Routes Preferred ou de l'API Route Optimization

1. Demandez un jeton d'itinéraire avec 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 Demander un jeton d'itinéraire.

   • API Routes Preferred: computeCustomRoutes. Pour en savoir plus sur la demande d'un jeton d'itinéraire 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 d'API Routes ou d'API Routes Preferred pour répondre aux exigences d'utilisation d'un jeton d'itinéraire :

   • Définissez travel_mode sur DRIVE ou TWO_WHEELER
   • Définissez routing_preference sur TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL
   • N'utilisez PAS les points de cheminement Via

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

1. Stockez le jeton d'itinéraire : dans le SDK Navigation, configurez une chaîne pour stocker le jeton d'itinéraire. 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 mapView.navigator setDestinations, en spécifiant les mêmes points de cheminement de destination que ceux utilisés lors de la création du jeton d'itinéraire :

   mapView.navigator?.continueToNextDestination([waypoint1, waypoint2], routeToken: routeToken, callback: {...})
   

   Remarque : Si vous devez emprunter à nouveau le même itinéraire, demandez un nouveau jeton d'itinéraire.

   La méthode Navigator.continueToNextDestination renvoie l'état de la requête. Si un itinéraire est trouvé entre l'emplacement de l'utilisateur et la destination indiquée, elle renvoie RouteStatus.OK.

Scénarios à plusieurs arrêts

Vous pouvez configurer jusqu'à 25 points de cheminement.

La méthode setDestinations n'est pas compatible avec les trajets à plusieurs arrêts. Utilisez continueToNextDestination() pour faire passer le point de cheminement à la section suivante du trajet.

Attention : L'appel de la méthode continueToNextDestination() peut parfois entraîner un événement d'arrivée incorrect, où la destination qui vient d'être atteinte semble être à nouveau sélectionnée.

Attention : Vous devez implémenter votre propre gestion des erreurs lorsque vous utilisez la méthode continueToNextDestination(), par exemple en vérifiant la présence d'un itinéraire sur la carte ou en surveillant l'état du navigateur afin de détecter les échecs. Ensuite, fournissez des conseils à l'utilisateur, par exemple en lui suggérant de se déplacer vers une zone où la connectivité est meilleure.

Exemple

Les exemples de code suivants montrent comment récupérer un itinéraire planifié.

Swift

let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)
let waypoint1 = GMSNavigationWaypoint(location: location, title: "waypoint from location")!
let waypoint2 = GMSNavigationWaypoint(placeID: "samplePlaceID", title: "waypoint from Place ID")!

let routeToken = "route token returned by Routes API"
mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})

Objective-C

CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);
GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:coordinate title:@"waypoint from location"];
GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@"samplePlaceID"
                                                                            title:@"waypoint from Place ID"];
NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator continueToNextDestination:@[waypoint1, waypoint2]
                         routeToken:routeToken
                           callback:^(GMSRouteStatus routeStatus){...}];

Interaction entre les jetons d'itinéraire et le SDK Navigation

Voici comment l'itinéraire généré par le SDK Navigation et l'itinéraire planifié dans le jeton d'itinéraire interagissent :

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

• Utilise le lieu de départ du véhicule.

• S'adapte aux conditions routières et de circulation. Consultez Pourquoi un itinéraire planifié peut ne pas être suivi exactement ?

• Ignore les options liées au routage suivantes, car elles ne sont pas nécessaires :

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• Suit:

  • Les options liées aux points de cheminement, telles que la préférence pour le côté de la route.

  • Les objectifs d'itinéraire. Si le SDK Navigation doit ajuster l'itinéraire renvoyé, il utilise les objectifs d'itinéraire que vous avez spécifiés lors de la demande du jeton d'itinéraire. Pour cette raison, vous devez utiliser les mêmes options liées aux points de cheminement que celles que vous avez spécifiées dans l'API Routes.