Planejar um trajeto

Observação: as atualizações na forma como o SDK de navegação segue as rotas planejadas estão sendo lançadas gradualmente e estarão disponíveis para todos os projetos até 22 de outubro de 2026. Até lá, a API Routes pode rejeitar solicitações que incluam betterRouteTimeTolerance.

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

Importante: o trajeto que os motoristas percorrem pode ser diferente do planejado. Mudanças no trânsito ou nas condições da via, o veículo saindo do trajeto planejado ou uma mudança para um trajeto mais rápido podem alterar o trajeto durante a viagem. Sempre que o SDK de navegação calcula um novo trajeto, ele usa as opções de trajeto definidas no token, como evitar pedágios.

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.

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

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.

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

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:

   • API Routes: computeRoutes. Para mais informações sobre como solicitar um token de trajeto na API Routes, consulte Calcular um trajeto e Receber 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 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 travelMode para DRIVE ou TWO_WHEELER.
   • Defina routingPreference para TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
   • Não use waypoints Via.

Observação: é possível especificar valores precisos de origem e destino, como entradas, docas de carga ou áreas de retirada designadas, no token de rota usando um token de ponto de navegação.

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:

   String 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 o método Navigator.setDestinations, especificando os mesmos waypoints de destino usados ao criar o token de trajeto:

   setDestinations(List destinations, CustomRoutesOptions customRoutesOptions, DisplayOptions displayOptions);

   Exemplo:

   CustomRoutesOptions customRoutesOptions =
         CustomRoutesOptions.builder()
         .setRouteToken(routeToken)
         .setTravelMode(TravelMode.DRIVING)
         .build();

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 encontrar um trajeto do local do veículo até o destino indicado, ele vai retornar RouteStatus.OK.

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

Exemplo

O exemplo de código a seguir demonstra como especificar um trajeto planejado usando um token de trajeto.

    ArrayList <Waypoint> destinations = Lists.newArrayList();
    Waypoint waypoint1 =
       Waypoint.builder()
          .setLatLng(10, 20)
          .setTitle("title")
          .setVehicleStopover(true)
          .build();
    destinations.add(waypoint1);
    Waypoint waypoint2 =
       Waypoint.builder()
          .setPlaceId("ChIJYV-J-ziuEmsRIMyoFaMedU4")
          .setTitle("title")
          .setVehicleStopover(true)
           .build();
    destinations.add(waypoint2);

    String routeToken = "route token returned by Routes API";

    CustomRoutesOptions customRoutesOptions =
       CustomRoutesOptions.builder()
          .setRouteToken(routeToken)
          .setTravelMode(TravelMode.DRIVING)
          .build();

    // Existing flow to get a Navigator.
    NavigationApi.getNavigator(...);

    // Existing flow for requesting routes.
    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions);

    // Or with display options.
    DisplayOptions displayOptions = new DisplayOptions();

    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions, displayOptions);

Observação :é possível configurar no máximo 25 paradas.

Como os tokens de trajeto e o SDK do Navigation interagem

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

• Substitui todos os destinos definidos anteriormente.

• Usa o local de partida do veículo.

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

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

  • RoutingOptions.avoidHighways()
  • RoutingOptions.avoidTolls()
  • RoutingOptions.avoidFerries()
  • Navigator.setLicensePlateRestrictionInfo()
  • 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.