Pianificare un percorso

A volte potresti voler pianificare il percorso fornito dall'app agli utenti. L'utilizzo di un token di route dall'API Routes (o dall'API Routes Preferred) può aiutarti a specificare due cose per il percorso pianificato:

• Una polilinea per il percorso.

• Obiettivi del percorso

Ad esempio, ecco alcuni esempi di obiettivi di routing che potresti avere:

• Riduci al minimo i tempi di consegna: un'attività che effettua la consegna di cibo potrebbe voler ridurre al minimo il tempo necessario per la consegna.

• Riduci al minimo i tempi di percorrenza o il consumo di carburante: un'attività di logistica potrebbe voler migliorare l'efficienza degli autisti e ridurre i costi del carburante.

• Riduci al minimo il tempo necessario per la destinazione: un'operazione di invio del servizio potrebbe voler ridurre al minimo il tempo necessario per portare gli operatori a una richiesta di job.

• Riduzione dei costi e miglioramento della sicurezza: un'attività di ride sharing potrebbe voler trovare un percorso che costi meno per i passeggeri e che eviti determinate aree per motivi di sicurezza.

Importante: il percorso effettivo seguito può variare rispetto al percorso pianificato fornito dal token. Eventuali variazioni del traffico, delle condizioni stradali o di un veicolo che si discosta dal percorso specificato possono comportare cambiamenti nel percorso. Man mano che si verificano modifiche, l'SDK di navigazione tenta continuamente di tornare al percorso pianificato oppure, se la restituzione non è pratica, segue gli obiettivi del percorso nel token del percorso.

Per ulteriori informazioni sulla pianificazione di una route utilizzando un token di route, consulta Richiedere un token di route.

Perché utilizzare un token di route per gli obiettivi delle route

Con un token di route dell'API Routes o Routes Preferred, hai un maggiore controllo sulla route fornita:

• Pianifica un percorso in anticipo per l'SDK di navigazione da utilizzare quando possibile.

• Scegli il percorso migliore da utilizzare per l'SDK di navigazione. Se richiedi token di route durante la generazione di route nell'API Routes, ricevi un token di route per ogni route generata. Puoi quindi scegliere il token per il percorso da utilizzare quando lo passi all'SDK di navigazione.

• Fai una stima del prezzo in anticipo, comprese le stime di orario di arrivo stimato e la distanza. Anche se il costo e i tempi effettivi possono variare, questa stima riduce il divario tra il costo del percorso previsto ed effettivo.

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

Suggerimento: un token di route è per un'origine e una destinazione specifiche e in un momento specifico. Devi effettuare una nuova richiesta API Routes per un nuovo token di route.

Come funzionano i token di route dell'API Routes

Puoi utilizzare l'API Routes o l'API Routes Preferred per pianificare un percorso utilizzando gli obiettivi del percorso. L'API Routes restituisce un token di percorso che puoi passare all'SDK di navigazione per guidare il modo in cui indirizza il tuo veicolo.

Ecco cosa succede quando richiedi e utilizzi un token di route dall'API Routes:

1. L'API Routes restituisce un token di route criptato che include la polilinea della route e gli obiettivi della route.

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

3. L'SDK di navigazione recupera il percorso oppure, se il percorso non è disponibile a causa di condizioni variabili, recupera il percorso migliore corrispondente.

4. Durante la guida, se il traffico o altre condizioni stradali cambiano o se un veicolo devia dal percorso pianificato, i percorsi modificati tentano continuamente di corrispondere al percorso migliore in base agli obiettivi del percorso nel token.

Questo processo massimizza la vicinanza del percorso effettivo al percorso pianificato.

Perché un percorso pianificato potrebbe non essere seguito esattamente

Pensa al percorso pianificato e agli obiettivi del percorso come linee guida da seguire: non sono prescrittivi. Potresti notare una differenza tra il percorso pianificato e quello fornito dalla navigazione guidata a causa di differenze nelle condizioni stradali, nella posizione di partenza o in altri parametri che sono stati modificati da quando hai creato il percorso pianificato. Questa differenza può determinare, tra le altre qualità importanti del viaggio, una mancata corrispondenza tra gli obiettivi pianificati e quelli effettivi per la distanza e l'orario di arrivo stimato.

Suggerimento: come best practice, richiedi sempre un nuovo token di route ogni volta che imposti la destinazione nell'SDK di navigazione e pianifica qualche variazione per evitare conseguenze sulla tua attività.

Pianificare un percorso utilizzando un token di route

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

Passaggio 1: crea un token di route utilizzando l'API Routes o Routes Preferred

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

   • API Routes: computeRoutes. Per ulteriori informazioni sulla richiesta di un token di route nell'API Routes, consulta Calcolare una route e Richiedere un token di route.

   • API preferita di Routes: computeCustomRoutes. Per ulteriori informazioni sulla richiesta di un token di route nell'API Routes Preferred, consulta Pianificare un percorso.

2. Configura la richiesta di route per soddisfare i requisiti per l'utilizzo di un token di route:

   • Imposta travel_mode su DRIVING
   • Imposta routing_preference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL
   • NON utilizzare Via waypoint

Passaggio 2: passa il token di route all'SDK di navigazione

1. Archivia il token di route: nell'SDK di navigazione, imposta una stringa per archiviare il token di route. Ad esempio:

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

   Esempio di token di route restituito:

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

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

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

   Ad esempio:

   CustomRoutesOptions customRoutesOptions =
         CustomRoutesOptions.builder()
         .setRouteToken(routeToken)
         .build();

Nota: se devi ripetere 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 ulteriori informazioni su questo metodo, consulta Navigator.setDestinations.

Esempio

Il seguente esempio di codice mostra come specificare una route pianificata utilizzando un token di route.

    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(CustomRoutesOptions.TravelMode.TWO_WHEELER)
          .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);

Come interagiscono i token di route e l'SDK di navigazione

Ecco come interagiscono il percorso generato dall'SDK di navigazione e il percorso pianificato nel token di route:

• Sostituisce tutte le destinazioni impostate in precedenza.

• Utilizza il luogo di partenza del veicolo.

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

• Ignora se non necessarie le seguenti opzioni relative al routing:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• Segue:

  • Opzioni correlate ai waypoint, ad esempio la preferenza relativa al lato della strada.

  • Obiettivi del percorso. Se l'SDK di navigazione deve modificare il percorso restituito, utilizza gli obiettivi della route specificati quando hai richiesto il token della route. Per questo motivo, devi utilizzare le stesse opzioni relative ai waypoint specificate nell'API Routes.