Planejar um trajeto

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

Para mais informações sobre como planejar um trajeto usando um token de rota, consulte Solicitar 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 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 trajetos na API Routes, vai receber um token para cada trajeto gerado. 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:

  1. As APIs Routes, Routes Preferred ou Route Optimization retornam um token de rota criptografado que inclui a polilinha e os objetivos do trajeto.

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

  3. O SDK Navigation recupera o trajeto ou, se ele não estiver disponível devido a mudanças nas condições, recupera o trajeto mais adequado.

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

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

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

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

    Exemplo de um token de rota retornado:

    {
    // Other fields
    "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
    }
    
  2. Transmita o token de rota para o SDK Navigation usando o método Navigator.setDestinations, especificando os mesmos pontos de parada de destino que você usou ao criar o token de rota:

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

    Exemplo:

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

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 retornarRouteStatus.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);

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.

  • Usa o local de partida do veículo.

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

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

    • avoidsHighways
    • avoidsTolls
    • avoidsFerries
    • licensePlateRestriction
  • Seguidores:

    • Opções relacionadas ao ponto de parada, 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.