Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Il peut arriver que vous souhaitiez planifier l'itinéraire que votre application fournit aux utilisateurs. L'utilisation d'un jeton d'itinéraire provenant des API Routes, Routes Preferred ou Route Optimization peut vous aider à spécifier deux éléments pour votre itinéraire planifié :
Polyligne pour l'itinéraire
Vos objectifs d'itinéraire
Voici quelques exemples d'objectifs de routage que vous pouvez définir :
Minimiser le délai de livraison : une entreprise de livraison de repas peut vouloir minimiser le temps nécessaire pour livrer les repas.
Minimiser le temps de trajet ou la consommation de carburant : une entreprise de logistique peut souhaiter améliorer l'efficacité de ses chauffeurs et réduire ses coûts de carburant.
Minimiser le temps de trajet : une opération de répartition des services peut vouloir minimiser le temps nécessaire pour que les opérateurs répondent à une demande d'intervention.
Réduire les coûts et améliorer la sécurité : une entreprise de covoiturage peut vouloir trouver un itinéraire qui coûte moins cher aux passagers et qui évite certaines zones pour des raisons de sécurité.
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 Transition Polylines and Route Tokens (Polylignes de transition et jetons d'itinéraire) dans l'API Route Optimization.
Pourquoi utiliser un jeton de route pour les objectifs de route ?
Avec un jeton d'itinéraire provenant des API Routes, Routes Preferred ou 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 l'estimation de l'heure d'arrivée 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 du trajet attendu et le coût réel.
Spécifiez des objectifs d'itinéraire plus avancés, comme un itinéraire écologique ou le plus court.
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 de route renvoyé par l'une de ces API au SDK Navigation pour guider la façon dont il calcule l'itinéraire de votre véhicule.
Voici ce qui se passe lorsque vous demandez et utilisez un jeton de route :
L'API Routes, l'API Routes Preferred ou l'API Route Optimization renvoient un jeton d'itinéraire chiffré qui inclut la polyligne et les objectifs de l'itinéraire.
Vous transmettez le jeton de route au SDK Navigation.
Le SDK Navigation récupère l'itinéraire ou, si celui-ci n'est pas disponible en raison de conditions changeantes, il récupère l'itinéraire le plus adapté.
Pendant le trajet, si le trafic ou les conditions de circulation changent, ou si un véhicule s'écarte de l'itinéraire prévu, les itinéraires modifiés tentent en permanence de correspondre au meilleur itinéraire en fonction des objectifs de l'itinéraire dans le jeton.
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
Considérez votre itinéraire planifié et vos objectifs d'itinéraire comme des consignes à suivre, et non comme des règles strictes. Il peut y avoir une différence entre l'itinéraire que vous avez planifié et celui fourni par la navigation guidée. Cela peut être dû à des différences dans les conditions de circulation, le point 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 un écart 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.
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 d'itinéraire à l'aide de l'API Routes, de l'API Routes Preferred ou de l'API Route Optimization
Demandez un jeton de route à l'aide de l'une des méthodes suivantes :
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 de route dans l'API Route Optimization, consultez Polylignes de transition et jetons de route.
Configurez votre requête API Routes ou API Routes Preferred pour répondre aux exigences d'utilisation d'un jeton de route :
Définissez travel_mode sur DRIVING ou TWO_WHEELER
Définissez routing_preference sur TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL
NE PAS utiliser Via points de cheminement
Étape 2 : Transmettez le jeton d'itinéraire au SDK Navigation
Stockez le jeton de route : dans le SDK Navigation, configurez une chaîne pour stocker le jeton de route. Exemple :
letrouteToken="route token returned by Routes API"
Exemple de jeton d'itinéraire renvoyé :
{// Other fields"routeToken":"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",}
Transmettez le jeton de route au SDK Navigation à l'aide de la méthode mapView.navigator setDestinations, en spécifiant les mêmes waypoints de destination que ceux utilisés lors de la création du jeton de route :
La méthode Navigator.setDestinations renvoie l'état de la requête.
Si un itinéraire est trouvé entre la position de l'utilisateur et la destination indiquée, la méthode renvoieRouteStatus.OK.
Les exemples de code suivants montrent comment récupérer un itinéraire planifié.
Swift
letlocation=CLLocationCoordinate2D(latitude:47.67,longitude:-122.20)letwaypoint1=GMSNavigationWaypoint(location:location,title:"waypoint from location")!letwaypoint2=GMSNavigationWaypoint(placeID:"samplePlaceID",title:"waypoint from Place ID")!letrouteToken="route token returned by Routes API"mapView.navigator?.setDestinations([waypoint1,waypoint2],routeToken:routeToken,callback:{...})
Objective-C
CLLocationCoordinate2Dlocation=CLLocationCoordinate2DMake(47.67,-122.20);GMSNavigationWaypoint*waypoint1=[[GMSNavigationWaypointalloc]initWithLocation:coordinatetitle:@"waypoint from location"];GMSNavigationWaypoint*waypoint2=[[GMSNavigationWaypointalloc]initWithPlaceID:@"samplePlaceID"title:@"waypoint from Place ID"];NSString*routeToken=@"route token returned by Routes API";[mapView.navigatorsetDestinations:@[waypoint1,waypoint2]routeToken:routeTokencallback:^(GMSRouteStatusrouteStatus){...}];
Interaction entre les jetons de route et le SDK Navigation
Voici comment la route générée par le SDK Navigation et la route planifiée dans le jeton de route interagissent :
Remplace toutes les destinations définies précédemment.
Ignore les options liées au routage suivantes, car elles ne sont pas nécessaires :
avoidsHighways
avoidsTolls
avoidsFerries
licensePlateRestriction
Abonnés :
Options liées aux points de repère, comme la préférence pour le côté de la route.
Objectifs de l'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 waypoints que celles que vous avez spécifiées dans l'API Routes.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/08/31 (UTC).
[null,null,["Dernière mise à jour le 2025/08/31 (UTC)."],[[["\u003cp\u003eRoute tokens let you plan routes in advance, optimizing for factors like time, fuel, or safety, and can be generated using the Routes, Routes Preferred, or Route Optimization API.\u003c/p\u003e\n"],["\u003cp\u003eWhile the Navigation SDK attempts to follow the planned route, real-world conditions may cause deviations; it dynamically adjusts while prioritizing the specified route objectives.\u003c/p\u003e\n"],["\u003cp\u003eYou create a route token via the Routes, Routes Preferred, or Route Optimization API, then pass it to the Navigation SDK's \u003ccode\u003esetDestinations\u003c/code\u003e method alongside your waypoints.\u003c/p\u003e\n"],["\u003cp\u003eThe Navigation SDK prioritizes the route token's plan but dynamically adapts to real-time conditions, potentially leading to variations between the planned and actual route.\u003c/p\u003e\n"],["\u003cp\u003eAlways request a fresh route token for each trip and anticipate potential route adjustments to ensure smooth navigation and accurate estimations.\u003c/p\u003e\n"]]],[],null,["# Plan a route\n\nAt times, you might want to plan the route your app provides to users. Using a\nroute token from the Routes API,\nRoutes Preferred API, or Route Optimization API can\nhelp you specify two things for your planned route:\n\n- A polyline for the route\n\n- Your route objectives\n\nFor example, here are some examples of routing objectives you may have:\n\n- **Minimize time to delivery**: A business delivering food might want to\n minimize the time it takes to deliver the food.\n\n- **Minimize travel time or fuel consumption**: A logistics business might\n want to improve the efficiency of their drivers and reduce their fuel costs.\n\n- **Minimize time to destination**: A service dispatch operation might want to\n minimize the time it takes to get operators to a job request.\n\n- **Lower costs and improve safety**: A ride-sharing business might want to\n find a route that costs less for riders and avoids certain areas for safety\n reasons.\n\n| **Important:** The actual route traveled may vary from the planned route provided by the token. Changing traffic, road conditions, or the vehicle deviating from the given route can result in route changes. As changes occur, the Navigation SDK continually attempts to return to the planned route, or if returning is impractical, follows the route objectives in the route token.\n\nFor more information about planning a route using a route token, see [Request a\nroute token](/maps/documentation/routes/choose_fields#route-token) in\nRoutes API and [Transition Polylines and Route\nTokens](/maps/documentation/route-optimization/polylines-and-route-tokens) in\nRoute Optimization API.\n\nWhy use a route token for route objectives\n------------------------------------------\n\nWith a route token from the Routes API,\nRoutes Preferred API, or Route Optimization API, you\nhave more control over the route provided:\n\n- **Plan a route in advance** for the Navigation SDK to use when\n possible.\n\n- **Choose the best route for the Navigation SDK to use**. If you\n request route tokens when generating routes in the Routes API,\n you get a route token for each generated route. You can then choose the\n token for the route you want to use when you pass it to the\n Navigation SDK.\n\n- **Estimate the price in advance**, including estimations for ETA and\n distance. While the actual cost and time might vary, this estimation reduces\n the gap between expected and actual route cost.\n\n- **Specify more advanced route objectives**, such as eco routing or the\n shortest route.\n\n| **Tip:** A route token is for one specific origin and destination and at a particular time. You must make a new Routes API, Routes Preferred API, or Route Optimization API request for a new route token.\n\nHow route tokens work\n---------------------\n\nYou can use the Routes API, Routes Preferred API, or\nRoute Optimization API to plan a route using route objectives. You\ncan pass a route token returned from any of these APIs to the\nNavigation SDK to guide how it routes your vehicle.\n\nHere's what happens when you request and use a route token:\n\n1. The Routes API, Routes Preferred API, or\n Route Optimization API returns an encrypted route token that\n includes the route polyline and route objectives.\n\n2. You pass the route token to the Navigation SDK.\n\n3. The Navigation SDK retrieves the route, or if the route is not\n available due to changing conditions, it retrieves the best matching route.\n\n4. While driving the route, if traffic or other road conditions change, or if a\n vehicle deviates from the planned route, the modified routes continually\n attempt to match the best route based on the route objectives in the token.\n\nThis process maximizes how close the actual route is to your planned route.\n\n### Why a planned route may not be followed exactly\n\nThink of your planned route and route objectives as guidelines to follow: they\nare not prescriptive. You might see a difference between your planned route and\nthe route provided by guided navigation due to differences in the road\nconditions, starting location, or other parameters that have changed since you\ncreated the planned route. This difference might result in a mismatch between\nyour planned and actual goals for distance and ETA, among other important trip\nqualities.\n| **Tip:** As a best practice, always request a new route token every time you set the destination in the Navigation SDK, and plan for some variation to avoid any impact to your business.\n\nPlan a route using a route token\n--------------------------------\n\nYou can plan a route by creating a route token and then passing it to the\nNavigation SDK, as described in the following steps:\n\n### Step 1: Create a route token using the Routes API, Routes Preferred API, or Route Optimization API\n\n1. **Request a route token** with one of the following methods:\n\n - **Routes API** : `computeRoutes`. For more information\n about requesting a route token in the Routes API, see\n [Compute a route](/maps/documentation/routes/compute_route_directions)\n and [Request a route\n token](/maps/documentation/routes/choose_fields#route-token).\n\n - **Routes Preferred API** : `computeCustomRoutes`. For more\n information about requesting a route token in the\n Routes Preferred API, see [Plan a\n route](/maps/documentation/routes_preferred/custom_routes).\n\n - **Route Optimization API** : `optimizeTours` or\n `batchOptimizeTours`. For more information about requesting a route\n token in the Route Optimization API, see [Transition Polylines and Route\n Tokens](/maps/documentation/route-optimization/polylines-and-route-tokens).\n\n2. **Set up your Routes API or Routes Preferred API\n request** to meet the requirements for using a route token:\n\n - Set `travel_mode` to `DRIVING` or `TWO_WHEELER`\n - Set `routing_preference` to `TRAFFIC_AWARE` or `TRAFFIC_AWARE_OPTIMAL`\n - Do NOT use `Via` waypoints\n\n### Step 2: Pass the route token to the Navigation SDK\n\n1. **Store the route token**: In the Navigation SDK, set up a string\n to store the route token. For example:\n\n let routeToken = \"route token returned by Routes API\"\n\n Example of a returned route token: \n\n {\n // Other fields\n \"routeToken\": \"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g\",\n }\n\n2. **Pass the route token** to the Navigation SDK using the\n `mapView.navigator setDestinations` method, specifying the same destination\n waypoints that you used when creating the route token:\n\n mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})\n\n| **Note:** If you need to travel the same route again, request a new route token.\n\nThe `Navigator.setDestinations` method returns the status of the request.\nIf a route is found from the user's location to the given destination,\nit returns`RouteStatus.OK`.\n\nFor more information about this method, see\n[`GMSNavigator.setDestinations`](/maps/documentation/navigation/ios-sdk/reference/objc/Classes/GMSNavigator#-setdestinations:callback:).\n\n### Example\n\nThe following code examples demonstrate how to retrieve a planned route.\n\n\u003cbr /\u003e\n\n### Swift\n\n\u003cbr /\u003e\n\n let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)\n let waypoint1 = GMSNavigationWaypoint(location: location, title: \"waypoint from location\")!\n let waypoint2 = GMSNavigationWaypoint(placeID: \"samplePlaceID\", title: \"waypoint from Place ID\")!\n\n let routeToken = \"route token returned by Routes API\"\n mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})\n\n\u003cbr /\u003e\n\n### Objective-C\n\n\u003cbr /\u003e\n\n CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);\n GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:coordinate title:@\"waypoint from location\"];\n GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@\"samplePlaceID\"\n title:@\"waypoint from Place ID\"];\n NSString *routeToken = @\"route token returned by Routes API\";\n\n [mapView.navigator setDestinations:@[waypoint1, waypoint2]\n routeToken:routeToken\n callback:^(GMSRouteStatus routeStatus){...}];\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nHow route tokens and the Navigation SDK interact\n------------------------------------------------\n\nHere's how the route generated by the Navigation SDK and the planned\nroute in the route token interact:\n\n- **Overrides** any previously-set destinations.\n\n- **Uses** the vehicle starting location.\n\n- **Adjusts** for road and traffic conditions. See\n [Why a planned route might not be followed exactly](#not-followed).\n\n- **Ignores** the following routing-related options as unneeded:\n\n - `avoidsHighways`\n - `avoidsTolls`\n - `avoidsFerries`\n - `licensePlateRestriction`\n- **Follows**:\n\n - **Waypoint-related options**, such as the side-of-road preference.\n\n - **Route objectives**. If the Navigation SDK has to\n adjust the returned route, it uses the route objectives you specified when\n requesting the route token. For this reason, you should use the same\n waypoint-related options that you specified in Routes API."]]
