Planejar um trajeto

Às vezes, você pode querer planejar o trajeto que seu app oferece aos usuários. Usar um token de trajeto 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 o trajeto

• Seus objetivos de trajeto

Confira alguns exemplos de objetivos de trajeto que você pode ter:

• Minimizar o tempo de entrega: uma empresa de entrega de comida pode querer minimizar o tempo necessário para entregar o pedido.

• 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 despacho de serviços 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 compartilhamento de viagens pode querer encontrar um trajeto 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 por o token. Mudanças no trânsito, nas condições das vias ou no desvio do veículo do trajeto fornecido podem resultar em mudanças no trajeto. À medida que as mudanças ocorrem, o SDK de navegação tenta continuamente retornar ao trajeto planejado ou, se o retorno for impraticável, segue os objetivos do trajeto no token.

Para mais informações sobre como planejar um trajeto usando um token de trajeto, consulte Solicitar um token de trajeto na API Routes e Polilinhas de transição e tokens de trajeto na API Route Optimization.

Por que usar um token de trajeto para objetivos de trajeto

Com um token de trajeto 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 o SDK de navegação usar quando possível.

• Escolha o melhor trajeto para o SDK de navegação usar. Se você solicitar tokens de trajeto ao gerar trajetos na API Routes, receberá um token de trajeto para cada trajeto gerado. Em seguida, escolha o token do trajeto 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 do trajeto.

• Especifique objetivos de trajeto mais avançados, como o trajeto ecológico ou o mais curto.

Dica: um token de trajeto é para uma origem e um destino específicos e em um horário específico. Você precisa fazer uma nova solicitação da API Routes, da API Routes Preferred ou da API Route Optimization para um novo token de trajeto.

Como os tokens de trajeto funcionam

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

Veja o que acontece quando você solicita e usa um token de trajeto:

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

2. Você transmite o token de trajeto para o SDK de navegação.

3. O SDK de navegação recupera o trajeto ou, se o trajeto não estiver disponível devido a condições variáveis, ele recupera o trajeto mais adequado.

4. Ao dirigir o trajeto, se o trânsito ou outras condições da via mudarem, ou se um veículo se desviar do trajeto planejado, os trajetos modificados tentarão continuamente corresponder ao melhor trajeto com base nos objetivos do trajeto no token.

Esse processo maximiza a proximidade do trajeto real ao trajeto planejado.

Por que um trajeto planejado pode não ser seguido exatamente

Pense no trajeto planejado e nos objetivos do trajeto como diretrizes a serem seguidas: eles não são prescritivos. Você pode notar uma diferença entre o trajeto planejado e o trajeto 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.

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

Planejar um trajeto usando um token de trajeto

Você pode planejar um trajeto criando um token de trajeto 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 Routes Preferred ou a API Route Optimization

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

   • API Routes: computeRoutes. Para mais informações sobre como solicitar um token de trajeto na API Routes, consulte Calcular um trajeto e Solicitar um token de trajeto.

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

   • API Route Optimization: optimizeTours ou batchOptimizeTours. Para mais informações sobre como solicitar um token de trajeto na API Route Optimization, consulte Polilinhas de transição e tokens de trajeto.

2. Configure sua solicitação da API Routes ou da API Routes Preferred para atender aos requisitos de uso de um token de trajeto:

   • Defina travel_mode como DRIVE ou TWO_WHEELER
   • Defina routing_preference como TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL
   • NÃO use waypoints Via

Observação: você pode especificar valores de origem e destino precisos, como entradas, docas de carregamento ou áreas de coleta designadas, no token de trajeto usando um token de ponto de navegação.

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

1. Armazene o token de rota: no SDK de navegação, configure uma string para armazenar o token de rota. Por 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 trajeto para o SDK de navegação usando mapView.navigator.setDestinations. Especifique os mesmos waypoints de destino que você usou ao criar o token de trajeto:

   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 um trajeto for encontrado do local do usuário para o destino fornecido, ele retornará RouteStatus.OK.

Cenários de várias paradas

Você pode configurar um máximo de 25 waypoints.

O método setDestinations não oferece suporte a viagens com várias paradas. Use continueToNextDestinationWithCompletion() para avançar o waypoint para a próxima etapa da viagem.

**Cuidado**: chamar o método continueToNextDestinationWithCompletion() às vezes pode resultar em um evento de chegada incorreto, em que o destino recém-concluído parece ser selecionado novamente.

Exemplo

Os exemplos de código a seguir demonstram como recuperar um trajeto planejado.

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){...}];

Como os tokens de trajeto e o SDK de navegação interagem

Veja como o trajeto gerado pelo SDK de navegação e o trajeto planejado no token de trajeto interagem:

• Substitui todos os destinos definidos anteriormente.

• Usa o local de partida do veículo.

• Ajusta as condições da via e do trânsito. Consulte Por que um trajeto planejado pode não ser seguido exatamente.

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

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• Segue:

  • Opções relacionadas a waypoints, como a preferência de lado da via.

  • Objetivos de trajeto. Se o SDK de navegação precisar ajustar o trajeto retornado, ele usará os objetivos de trajeto especificados ao solicitar o token de trajeto. Por esse motivo, use as mesmas opções relacionadas a waypoints especificadas na API Routes.