Pianificare un percorso

Nota: gli aggiornamenti al modo in cui l'SDK di navigazione segue i percorsi pianificati verranno implementati gradualmente e saranno disponibili per tutti i progetti entro il 22 ottobre 2026. Fino ad allora, l'API Routes potrebbe rifiutare le richieste che includono betterRouteTimeTolerance.

A volte, potresti voler pianificare il percorso che la tua app fornisce agli utenti. L'utilizzo di un token di percorso dell'API Routes, dell'API Routes Preferred o dell'API Route Optimization può aiutarti a specificare due cose per il percorso pianificato:

• Una polilinea per il percorso

• I tuoi obiettivi di percorso

Ecco alcuni esempi di obiettivi di routing che potresti avere:

• Ridurre al minimo i tempi di consegna: un'attività di consegna di cibo potrebbe voler ridurre al minimo il tempo necessario per consegnare il cibo.

• Ridurre al minimo il tempo di percorrenza o il consumo di carburante: un'azienda di logistica potrebbe voler migliorare l'efficienza dei propri conducenti e ridurre i costi del carburante.

• Ridurre al minimo il tempo per raggiungere la destinazione: un'operazione di invio di servizi potrebbe voler ridurre al minimo il tempo necessario per far arrivare gli operatori a una richiesta di lavoro.

• Ridurre i costi e migliorare la sicurezza: un'attività di ride sharing potrebbe voler trovare un percorso che costi meno per i passeggeri ed eviti determinate aree per motivi di sicurezza.

Importante: il percorso seguito dai conducenti può essere diverso da quello pianificato. Le variazioni del traffico o delle condizioni stradali, l'uscita del veicolo dal percorso pianificato o il passaggio a un percorso più veloce possono modificare il percorso durante il viaggio. Ogni volta che l'SDK di navigazione calcola un nuovo percorso, utilizza le opzioni di routing impostate nel token di percorso, ad esempio per evitare i pedaggi.

Per ulteriori informazioni sulla pianificazione di un percorso utilizzando un token di percorso, consulta Ottieni un token di percorso nell'API Routes e Polilinee di transizione e token di percorso nell'API Route Optimization.

Perché utilizzare un token di percorso per gli obiettivi del percorso

Con un token di percorso dell'API Routes, dell'API Routes Preferred o dell'API Route Optimization, hai un maggiore controllo sul percorso fornito:

• Pianifica un percorso in anticipo per l'utilizzo dell'SDK Navigation.

• Scegli il percorso migliore da utilizzare per l'SDK Navigation. Se richiedi i token di percorso durante la generazione dei percorsi nell'API Routes, ricevi un token di percorso per ogni percorso generato. Puoi quindi scegliere il token per il percorso che vuoi utilizzare quando lo passi all'SDK di navigazione.

• Stima il prezzo in anticipo, incluse le stime per l'orario di arrivo stimato e la distanza. Sebbene il costo e il tempo effettivi possano variare, questa stima riduce il divario tra il costo del percorso previsto e quello effettivo.

• Specifica obiettivi di percorso più avanzati, come il percorso ecosostenibile o il percorso più breve.

Suggerimento: un token di percorso è relativo a un'origine e una destinazione specifiche e a un momento particolare. Devi effettuare una nuova richiesta all'API Routes, all'API Routes Preferred o all'API Route Optimization per un nuovo token di percorso.

Come funzionano i token di route

Puoi utilizzare l'API Routes, l'API Routes Preferred o l'API Route Optimization per pianificare un percorso utilizzando gli obiettivi del percorso. Puoi passare un token di percorso restituito da una di queste API all'SDK Navigation per guidare il modo in cui calcola il percorso del veicolo.

Ecco cosa succede quando richiedi e utilizzi un token di percorso:

1. L'API Routes, l'API Routes Preferred o l'API Route Optimization restituisce un token di percorso criptato che include la polilinea e gli obiettivi del percorso.

2. Passi il token di route all'SDK Navigation.

3. L'SDK Navigation avvia la navigazione sul percorso pianificato, anche se è disponibile un percorso più veloce.

4. Durante il viaggio, se il traffico o le condizioni stradali cambiano o se il veicolo esce dal percorso pianificato, l'SDK di navigazione calcola un nuovo percorso che segue gli obiettivi e le opzioni di routing impostati nel token di percorso.

Questo processo massimizza la vicinanza del percorso effettivo a quello pianificato.

Perché un percorso pianificato potrebbe non essere seguito esattamente

La navigazione inizia sul percorso pianificato, ma il percorso effettivo può differire da questo in situazioni come le seguenti:

• Il veicolo parte da un punto diverso da quello di partenza pianificato.
• Le condizioni del traffico o della strada cambiano durante il viaggio.
• Il veicolo abbandona il percorso pianificato.

Queste differenze possono influire sulla distanza, sull'orario di arrivo stimato e su altre importanti qualità del percorso che hai pianificato.

Suggerimento: come best practice, richiedi sempre un nuovo token di percorso ogni volta che imposti la destinazione nell'SDK di navigazione e pianifica alcune variazioni per evitare qualsiasi impatto sulla tua attività.

Pianifica un percorso utilizzando un token di percorso

Puoi pianificare un percorso creando un token di percorso e passandolo all'SDK Navigation, come descritto nei seguenti passaggi:

Passaggio 1: crea un token di percorso utilizzando l'API Routes, l'API Routes Preferred o l'API Route Optimization

1. Richiedi un token di percorso con uno dei seguenti metodi:

   • API Routes: computeRoutes. Per saperne di più sulla richiesta di un token di percorso nell'API Routes, consulta Calcola un percorso e Ottieni un token di percorso.

   • API Routes Preferred: computeCustomRoutes. Per saperne di più sulla richiesta di un token di percorso nell'API Routes Preferred, consulta Pianifica un percorso.

   • API Route Optimization: optimizeTours o batchOptimizeTours. Per ulteriori informazioni sulla richiesta di un token di percorso nell'API Route Optimization, consulta Polilinee di transizione e token di percorso.

2. Configura la richiesta dell'API Routes o dell'API Routes Preferred in modo che soddisfi i requisiti per l'utilizzo di un token di percorso:

   • Imposta travelMode su DRIVE o TWO_WHEELER.
   • Imposta routingPreference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
   • Non utilizzare i waypoint Via.

Nota: puoi specificare valori precisi di origine e destinazione, come ingressi, banchine di carico o aree di ritiro designate, nel token di route utilizzando un token di punto di navigazione.

Passaggio 2: passa il token di percorso all'SDK Navigation

1. Archivia il token di percorso: nell'SDK Navigation, configura una stringa per archiviare il token di percorso. Ad esempio:

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

   Esempio di token di route restituito:

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

2. Passa il token di percorso all'SDK Navigation utilizzando il metodo Navigator.setDestinations, specificando gli stessi waypoint di destinazione che hai utilizzato durante la creazione del token di percorso:

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

   Ad esempio:

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

Nota: se devi percorrere di nuovo lo stesso percorso, richiedi un nuovo token di percorso.

Il metodo Navigator.setDestinations restituisce lo stato della richiesta. Se trova un percorso dalla posizione del veicolo alla destinazione specificata, restituisce RouteStatus.OK.

Per saperne di più su questo metodo, consulta Navigator.setDestinations.

Esempio

L'esempio di codice seguente mostra come specificare un percorso pianificato utilizzando un token di percorso.

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

Nota: puoi configurare un massimo di 25 waypoint.

Interazione tra i token di percorso e l'SDK Navigation

Ecco come l'SDK Navigation gestisce il percorso pianificato:

• Sostituisce le destinazioni impostate in precedenza.

• Utilizza la posizione di partenza del veicolo.

• Si adatta alle condizioni della strada e del traffico. Consulta Perché un percorso pianificato potrebbe non essere seguito esattamente.

• Utilizza le opzioni di calcolo del percorso impostate nel token di percorso anziché le seguenti impostazioni nell'app, anche quando calcola un nuovo percorso durante il viaggio:

  • RoutingOptions.avoidHighways()
  • RoutingOptions.avoidTolls()
  • RoutingOptions.avoidFerries()
  • Navigator.setLicensePlateRestrictionInfo()
  • La modalità di viaggio impostata nell'app

• Segue queste impostazioni quando calcola o modifica il percorso:

  • Obiettivi del percorso dal token del percorso, ad esempio il percorso ecologico o il percorso più breve. Se l'SDK di navigazione deve modificare il percorso, utilizza gli obiettivi del percorso specificati quando hai richiesto il token del percorso.

  • Opzioni relative ai waypoint della tua app, ad esempio la preferenza per il lato della strada. Utilizza le stesse opzioni relative ai waypoint che hai specificato quando hai richiesto il token di route.