Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
A volte potresti voler pianificare il percorso che la tua app fornisce agli utenti. L'utilizzo di un
token di percorso dall'API Routes, dall'API Routes Preferred o dall'API Route Optimization può
aiutarti a specificare due cose per l'itinerario pianificato:
Una polilinea per l'itinerario
Gli obiettivi del percorso
Ad esempio, ecco alcuni esempi di obiettivi di routing che potresti avere:
Ridurre al minimo i tempi di consegna: un'attività che consegna cibo potrebbe voler
ridurre al minimo i tempi di consegna.
Ridurre al minimo i tempi di viaggio o il consumo di carburante: un'attività di logistica potrebbe
voler migliorare l'efficienza dei propri conducenti e ridurre i costi del carburante.
Ridurre al minimo il tempo per raggiungere la destinazione: un'operazione di invio del servizio potrebbe voler
ridurre al minimo il tempo necessario agli operatori per rispondere a una richiesta di lavoro.
Costi inferiori e maggiore sicurezza: un'attività di ride sharing potrebbe voler trovare un percorso che costi meno per i passeggeri ed eviti determinate aree per motivi di sicurezza.
Perché utilizzare un token di percorso per gli obiettivi di percorso
Con un token di percorso dell'API Routes,
dell'API Routes Preferred o dell'API Route Optimization,
hai un maggiore controllo sull'itinerario fornito:
Pianifica un percorso in anticipo da utilizzare con l'SDK Navigation quando
possibile.
Scegliere il percorso migliore da utilizzare per l'SDK Navigation. Se
richiedi token di percorso quando generi itinerari nell'API Routes,
ricevi un token di percorso per ogni itinerario generato. Puoi quindi scegliere il token per l'itinerario che vuoi utilizzare quando lo passi all'SDK Navigation.
Stima il prezzo in anticipo, incluse le stime per l'ETA e la distanza. Sebbene il costo e il tempo effettivi possano variare, questa stima riduce
il divario tra il costo previsto e quello effettivo dell'itinerario.
Specifica obiettivi di percorso più avanzati, come il percorso ecosostenibile o il percorso più breve.
Come funzionano i token di percorso
Puoi utilizzare l'API Routes, l'API Routes Preferred o
l'API Route Optimization per pianificare un itinerario utilizzando gli obiettivi dell'itinerario. Puoi
trasferire un token di percorso restituito da una di queste API all'SDK Navigation per guidare il percorso del tuo veicolo.
Ecco cosa succede quando richiedi e utilizzi un token di percorso:
L'API Routes, l'API Routes Preferred o
l'API Route Optimization restituiscono un token di percorso criptato che
include la polilinea del percorso e gli obiettivi del percorso.
Passi il token di percorso all'SDK Navigation.
L'SDK Navigation recupera l'itinerario oppure, se non è disponibile a causa di condizioni in evoluzione, recupera l'itinerario più corrispondente.
Durante la guida lungo il percorso, se il traffico o altre condizioni stradali cambiano o se un
veicolo si discosta dal percorso pianificato, i percorsi modificati tentano continuamente
di trovare il percorso migliore in base agli obiettivi del percorso nel token.
Questo processo massimizza la vicinanza del percorso effettivo a quello pianificato.
Perché un percorso pianificato potrebbe non essere seguito esattamente
Considera l'itinerario pianificato e gli obiettivi dell'itinerario come linee guida da seguire: non
sono prescrittivi. Potresti notare una differenza tra l'itinerario pianificato e
quello fornito dalla navigazione guidata a causa di differenze nelle condizioni
stradali, nella posizione di partenza o in altri parametri che sono cambiati da quando
hai creato l'itinerario pianificato. Questa differenza potrebbe causare una mancata corrispondenza tra
gli obiettivi pianificati e quelli effettivi per distanza e orario di arrivo stimato, tra le altre importanti
qualità del viaggio.
Pianificare un percorso utilizzando un token di percorso
Puoi pianificare un percorso creando un token di percorso e passandolo all'SDK Navigation, come descritto nei seguenti passaggi:
Passaggio 1: crea un token di percorso utilizzando l'API Routes, l'API Routes Preferred o l'API Route Optimization
Richiedi un token di percorso con uno dei seguenti metodi:
API Routes Preferred: computeCustomRoutes. Per ulteriori
informazioni sulla richiesta di un token di percorso nell'API Routes Preferred, consulta la sezione Pianificare un
itinerario.
API Route Optimization: optimizeTours o
batchOptimizeTours. Per saperne di più sulla richiesta di un token di percorso nell'API Route Optimization, consulta Transizione delle polilinee e dei token di percorso.
Configura la richiesta dell'API Routes o dell'API Routes Preferred in modo che soddisfi i requisiti per l'utilizzo di un token di percorso:
Imposta travel_mode su DRIVING o TWO_WHEELER
Imposta routing_preference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL
NON utilizzare Via waypoint
Passaggio 2: passa il token di percorso all'SDK Navigation
Memorizza il token di percorso: nell'SDK Navigation, configura una stringa
per memorizzare il token di percorso. Ad esempio:
letrouteToken="route token returned by Routes API"
Esempio di token di percorso restituito:
{// Other fields"routeToken":"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",}
Passa il token di percorso all'SDK Navigation utilizzando il metodo
mapView.navigator setDestinations, specificando gli stessi waypoint di destinazione
che hai utilizzato durante la creazione del token di percorso:
Il metodo Navigator.setDestinations restituisce lo stato della richiesta.
Se viene trovato un percorso dalla posizione dell'utente alla destinazione specificata,
viene restituitoRouteStatus.OK.
I seguenti esempi di codice mostrano come recuperare un percorso pianificato.
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){...}];
Come interagiscono i token di percorso e l'SDK Navigation
Ecco come interagiscono la route generata dall'SDK Navigation e la route pianificata nel token di route:
Sostituisce le destinazioni impostate in precedenza.
Ignora le seguenti opzioni relative al routing in quanto non necessarie:
avoidsHighways
avoidsTolls
avoidsFerries
licensePlateRestriction
Nuovi follower:
Opzioni relative alle tappe, ad esempio la preferenza per il lato della strada.
Obiettivi del percorso. Se l'SDK Navigation deve
modificare l'itinerario restituito, utilizza gli obiettivi dell'itinerario specificati quando
hai richiesto il token dell'itinerario. Per questo motivo, devi utilizzare le stesse
opzioni relative ai waypoint specificate nell'API Routes.
[null,null,["Ultimo aggiornamento 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."]]
