Planejar um trajeto

Às vezes, você pode querer planejar o trajeto que o app oferece aos usuários. O uso de um token de rota da API Routes, da API Routes Preferred ou da API Route Optimization pode ajudar a especificar duas coisas para o trajeto planejado:

• Uma polilinha para a rota

• Seus objetivos de trajeto

Confira alguns exemplos de objetivos de roteamento:

• Minimizar o tempo de entrega: uma empresa que entrega comida pode querer minimizar o tempo que leva para entregar a comida.

• 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 que leva para levar operadores a uma solicitação de trabalho.

• Reduzir custos e melhorar a segurança: uma empresa de transporte por aplicativo pode querer encontrar uma rota que custe menos para os passageiros e evite determinadas áreas por motivos de segurança.

Importante: o trajeto real percorrido pode variar do trajeto planejado fornecido pelo token. Mudanças no trânsito, condições da via ou desvios do veículo da rota podem resultar em mudanças na rota. À medida que as mudanças ocorrem, o SDK de navegação tenta continuamente retornar à rota planejada ou, se o retorno for impraticável, segue os objetivos da rota no token.

Para mais informações sobre como planejar uma rota usando um token de rota, consulte Solicitar um token de rota na API Routes e Transição de polilinhas e tokens de rota na API Route Optimization.

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 a rota fornecida:

• Planeje uma rota com antecedência para que o SDK de navegação a use quando possível.

• Escolher a melhor rota para o SDK do Navigation. Se você solicitar tokens de rota ao gerar rotas na API Routes, vai receber um token de rota para cada rota gerada. Em seguida, escolha o token da rota que você quer usar ao transmiti-lo ao SDK de navegação.

• 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 da rota.

• Especifique objetivos de rota mais avançados, como trajetos ecológicos ou a rota mais curta.

Dica: um token de rota é para uma origem e um destino específicos e em um horário específico. É necessário fazer uma nova solicitação de API Routes, API Routes Preferred ou API Route Optimization para receber um novo token de rota.

Como os tokens de rota funcionam

É possível usar a API Routes, a API Routes Preferred ou a API Route Optimization para planejar uma rota usando objetivos de rota. Você pode transmitir um token de rota retornado por qualquer uma dessas APIs ao SDK de navegação para orientar como ele roteia seu veículo.

Confira o que acontece quando você solicita e usa um token de rota:

1. A API Routes, a API Routes Preferred ou a API Route Optimization retorna um token de trajeto criptografado que inclui a poligonal do trajeto e os objetivos do trajeto.

2. Você transmite o token de rota para o SDK do Navigation.

3. O SDK de navegação recupera a rota ou, se ela não estiver disponível devido a condições variáveis, recupera a melhor rota correspondente.

4. Durante o trajeto, se o trânsito ou outras condições da via mudarem ou se um veículo desviar do trajeto planejado, as rotas modificadas vão tentar corresponder à melhor rota com base nos objetivos do trajeto no token.

Esse processo maximiza a proximidade da rota real com a planejada.

Por que uma rota planejada pode não ser seguida exatamente

Pense na rota planejada e nos objetivos da rota como diretrizes a serem seguidas: elas não são prescritivas. Talvez você note uma diferença entre a rota planejada e a rota fornecida 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 a rota planejada. Essa diferença pode resultar em uma incompatibilidade entre as metas planejadas e reais de distância e hora estimada de chegada, entre outras características importantes da viagem.

Dica: como prática recomendada, sempre solicite um novo token de rota sempre que definir o destino no SDK de navegação e planeje alguma variação para evitar qualquer impacto nos seus negócios.

Planejar uma rota usando um token de rota

É possível planejar uma rota criando um token de rota e transmitindo-o ao SDK de navegação, conforme descrito nas etapas a seguir:

Etapa 1: criar um token de trajeto usando a API Routes, a API Preferred Routes ou a API Route Optimization

1. Solicite um token de rota com um dos seguintes métodos:

   • API Routes: computeRoutes. Para mais informações sobre como solicitar um token de rota na API Routes, consulte Como calcular uma rota e Solicitar um token de rota.

   • API Routes Preferred: computeCustomRoutes. Para mais informações sobre como solicitar um token de rota na API Routes Preferred, consulte Planejar uma rota.

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

2. 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 waypoints Via

Etapa 2: transmitir o token de rota para o SDK de navegação

1. Armazenar o token de rota: no SDK de navegação, configure uma string para armazenar o token de rota. Exemplo:

   let routeToken = "route token returned by Routes API"

   Exemplo de um token de trajeto retornado:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Transmita o token de rota para o SDK Navigation usando o método mapView.navigator setDestinations, especificando os mesmos pontos de passagem de destino usados ao criar o token de rota:

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

Observação: se você precisar percorrer o mesmo trajeto novamente, solicite um novo token de trajeto.

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.

Para mais informações sobre esse método, consulte GMSNavigator.setDestinations.

Exemplo

Os exemplos de código abaixo demonstram como recuperar uma rota planejada.

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 setDestinations:@[waypoint1, waypoint2]
                         routeToken:routeToken
                           callback:^(GMSRouteStatus routeStatus){...}];

Como os tokens de rota e o SDK do Navigation interagem

Confira como a rota gerada pelo SDK de navegação e a rota planejada no token de rota interagem:

• Substitui qualquer destino definido anteriormente.

• Usar o local de partida do veículo.

• Ajusta as condições da via e do trânsito. Consulte Por que uma rota planejada pode não ser seguida exatamente.

• Ignora as seguintes opções relacionadas ao roteamento como desnecessárias:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• Seguidores:

  • Opções relacionadas a pontos de passagem, como a preferência de acostamento.

  • Objetivos da rota. Se o SDK de navegação precisar ajustar a rota retornada, ele vai usar os objetivos de rota especificados ao solicitar o token de rota. Por esse motivo, use as mesmas opções relacionadas a pontos de passagem que você especificou na API Routes.