Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Às vezes, você pode querer planejar o trajeto que seu app oferece aos usuários. Usar um
token de rota das APIs Routes, Routes Preferred ou Route Optimization pode
ajudar você a especificar duas coisas para o trajeto planejado:
Uma polilinha para o trajeto
Seus objetivos de trajeto
Por exemplo, confira alguns objetivos de roteamento que você pode ter:
Minimizar o tempo de entrega: uma empresa que entrega comida pode querer minimizar o tempo necessário para fazer a entrega.
Minimizar o tempo de viagem ou o consumo de combustível: uma empresa de logística pode querer melhorar a eficiência dos motoristas e reduzir os custos de combustível.
Minimizar o tempo até o destino: uma operação de envio de serviço pode querer
minimizar o tempo necessário para que os operadores atendam a uma solicitação de trabalho.
Reduzir custos e melhorar a segurança: uma empresa de carona compartilhada pode querer encontrar um trajeto que custe menos para os passageiros e evite determinadas áreas por motivos de segurança.
Por que usar um token de rota para objetivos de rota
Com um token de rota da API Routes, da API Routes Preferred ou da API Route Optimization, você tem mais controle sobre o trajeto fornecido:
Planeje um trajeto com antecedência para que o SDK Navigation use quando
possível.
Escolha a melhor rota para o SDK do Navigation usar. Se você solicitar tokens de rota ao gerar rotas na API Routes, vai receber um token para cada rota gerada. Em seguida, escolha o token da rota que você quer usar ao transmiti-lo para o SDK Navigation.
Estime o preço com antecedência, incluindo estimativas de ETA e distância. Embora o custo e o tempo reais possam variar, essa estimativa reduz a diferença entre o custo esperado e o real.
Especifique objetivos de rota mais avançados, como trajetos ecológicos ou o
mais curto.
Como os tokens de rota funcionam
Você pode usar as APIs Routes, Routes Preferred ou Route Optimization para planejar um trajeto usando objetivos de rota. Você pode transmitir um token de rota retornado por qualquer uma dessas APIs para o SDK Navigation e orientar como ele vai traçar a rota do seu veículo.
Veja o que acontece quando você solicita e usa um token de rota:
As APIs Routes, Routes Preferred ou Route Optimization retornam um token de rota criptografado que inclui a polilinha e os objetivos do trajeto.
Você transmite o token de rota para o SDK do Navigation.
O SDK Navigation recupera o trajeto ou, se ele não estiver disponível devido a mudanças nas condições, recupera o melhor trajeto correspondente.
Durante o trajeto, se o trânsito ou outras condições da via mudarem, ou se um veículo se desviar da rota planejada, as rotas modificadas tentarão continuamente corresponder ao melhor trajeto com base nos objetivos da rota no token.
Esse processo maximiza a proximidade entre o trajeto real e o planejado.
Por que um trajeto planejado pode não ser seguido exatamente
Pense no trajeto planejado e nos objetivos dele como diretrizes a serem seguidas, não como regras. Pode haver uma diferença entre o trajeto planejado e o fornecido pela navegação guiada devido a diferenças nas condições da via, no local de partida ou em outros parâmetros que mudaram desde que você criou o trajeto planejado. Essa diferença pode resultar em uma incompatibilidade entre
as metas planejadas e reais de distância e ETA, entre outras qualidades importantes da viagem.
Planejar uma rota usando um token de rota
Para planejar um trajeto, crie um token de trajeto e transmita-o para o SDK Navigation, conforme descrito nas etapas a seguir:
Etapa 1: criar um token de rota usando a API Routes, a API Routes Preferred ou a API Route Optimization
Solicite um token de rota com um dos seguintes métodos:
API Routes Preferred: computeCustomRoutes. Para mais informações sobre como solicitar um token de rota na API Routes Preferred, consulte Planejar um trajeto.
API Route Optimization: optimizeTours ou
batchOptimizeTours. Para mais informações sobre como solicitar um token de rota na API Route Optimization, consulte Polilinhas de transição e tokens de rota.
Configure sua solicitação da API Routes ou da API Routes Preferred para atender aos requisitos de uso de um token de rota:
Defina travel_mode como DRIVING ou TWO_WHEELER
Defina routing_preference como TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL
NÃO use Via waypoints
Etapa 2: transmitir o token de rota para o SDK Navigation
Armazenar o token de rota: no SDK Navigation, configure uma string
para armazenar o token de rota. Exemplo:
letrouteToken="route token returned by Routes API"
Exemplo de um token de rota retornado:
{// Other fields"routeToken":"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",}
Transmita o token de rota para o SDK Navigation usando o método
mapView.navigator setDestinations, especificando os mesmos pontos de parada de destino
que você usou ao criar o token de rota:
O método Navigator.setDestinations retorna o status da solicitação.
Se uma rota for encontrada do local do usuário até o destino especificado,
ela vai retornarRouteStatus.OK.
Os exemplos de código a seguir demonstram como recuperar um trajeto planejado.
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){...}];
Como os tokens de rota e o SDK do Navigation interagem
Veja como a rota gerada pelo SDK Navigation e a rota planejada
no token de rota interagem:
Substitui todos os destinos definidos anteriormente.
Ignora as seguintes opções relacionadas ao roteamento por serem desnecessárias:
avoidsHighways
avoidsTolls
avoidsFerries
licensePlateRestriction
Seguidores:
Opções relacionadas ao ponto de referência, como a preferência de lado da via.
Objetivos de rota. Se o SDK Navigation precisar ajustar o trajeto retornado, ele usará os objetivos especificados ao solicitar o token de trajeto. Por isso, use as mesmas opções relacionadas a pontos de parada especificadas na API Routes.
[null,null,["Última atualização 2025-09-04 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."]]
