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 você a especificar duas coisas para o trajeto planejado:

  • Uma polilinha para o trajeto

  • Seus objetivos de rota

Por exemplo, confira alguns exemplos de objetivos de roteamento que você pode ter:

  • Minimizar o tempo de entrega: uma empresa que entrega alimentos pode querer minimizar o tempo de 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 despacho de serviço pode querer minimizar o tempo que os operadores levam para chegar a uma solicitação de trabalho.

  • Reduzir custos e melhorar a segurança: uma empresa de transporte por aplicativo pode querer encontrar um trajeto mais barato para os passageiros e evitar certas áreas por motivos de segurança.

Para mais informações sobre como planejar um trajeto usando um token de rota, consulte Receber um token de rota na API Routes e Polilinhas de transição e tokens de rota 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 do Navigation usar.

  • Escolha o melhor trajeto para o SDK do Navigation usar. Se você solicitar tokens de trajeto ao gerar trajetos na API Routes, vai receber um token para cada trajeto gerado. Em seguida, escolha o token do trajeto que você quer usar ao transmiti-lo ao SDK do Navigation.

  • Estimar o preço com antecedência, incluindo estimativas de HEC 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.

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

Como funcionam os tokens de trajeto

Use a API Routes, a API Routes Preferred ou a API Route Optimization para planejar um trajeto usando objetivos de rota. Você pode transmitir um token de trajeto retornado de qualquer uma dessas APIs para o SDK do Navigation para orientar como ele traça o trajeto do 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 do Navigation.

  3. O SDK do Navigation inicia a navegação no trajeto planejado, mesmo que haja um mais rápido disponível.

  4. Durante a viagem, se as condições de trânsito ou da via mudarem ou se o veículo sair do trajeto planejado, o SDK de navegação vai calcular um novo trajeto que segue os objetivos e as opções de trajeto definidos no token de trajeto.

Esse processo maximiza a proximidade entre o trajeto real e o planejado.

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

A navegação começa no trajeto planejado, mas o trajeto real pode ser diferente em situações como as seguintes:

  • O veículo começa longe do ponto de partida planejado.
  • As condições do trânsito ou da via mudarem durante a viagem.
  • O veículo sai do trajeto planejado.

Essas diferenças podem afetar a distância, o HEC e outras qualidades importantes da viagem que você planejou.

Planejar um trajeto usando um token de trajeto

Para planejar um trajeto, crie um token de trajeto e transmita-o ao SDK do Navigation, conforme descrito nas etapas a seguir:

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

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

  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 travelMode para DRIVE ou TWO_WHEELER.
    • Defina routingPreference para TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
    • Não use waypoints Via.

Etapa 2: transmitir o token de trajeto para o SDK do Navigation

  1. Armazenar o token de trajeto: no SDK do Navigation, configure uma string para armazenar o token de trajeto. 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 ao SDK do Navigation usando mapView.navigator.setDestinations. Especifique os mesmos waypoints de destino usados ao criar o token de rota:

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

    O método setDestinations transmite o status da solicitação para o callback. Se encontrar um trajeto do local do usuário até o destino fornecido, o status será .OK (GMSRouteStatusOK).

Cenários com várias paradas

É possível configurar no máximo 25 paradas.

O método setDestinations não é compatível com trajetos com várias paradas. Use continueToNextDestinationWithCompletion() para avançar o waypoint para o próximo trecho da jornada.

Exemplo

Os exemplos de código a seguir mostram 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:location 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 trajeto e o SDK do Navigation interagem

Veja como o SDK do Navigation lida com o trajeto planejado:

  • Usa as opções de trajeto definidas no token de trajeto em vez das seguintes configurações no app, inclusive ao calcular um novo trajeto durante a viagem:

    • avoidsHighways
    • avoidsTolls
    • avoidsFerries
    • licensePlateRestriction
    • O meio de transporte definido no app

  • Segue estas configurações ao calcular ou ajustar o trajeto:

    • Objetivos do trajeto do seu token de trajeto, como trajeto ecológico ou o trajeto mais curto. Se o SDK de navegação precisar ajustar o trajeto, ele vai usar os objetivos especificados quando você solicitou o token de trajeto.

    • Opções relacionadas a pontos de referência do seu app, como a preferência de lado da via. Use as mesmas opções relacionadas a waypoints que você especificou ao solicitar o token de trajeto.