Pianificare un percorso

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

• Una polilinea per l'itinerario

• Gli obiettivi del percorso

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

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

• Ridurre al minimo i tempi di viaggio o il consumo di carburante: un'attività 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 del servizio potrebbe voler ridurre al minimo il tempo necessario agli operatori per rispondere a una richiesta di lavoro.

• Costi inferiori e maggiore 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: l'itinerario effettivo percorso può variare rispetto a quello pianificato fornito dal token. Il cambiamento del traffico, delle condizioni stradali o la deviazione del veicolo dal percorso indicato possono comportare modifiche al percorso. Man mano che si verificano modifiche, l'SDK Navigation tenta continuamente di tornare all'itinerario pianificato oppure, se il ritorno è impraticabile, segue gli obiettivi dell'itinerario nel token dell'itinerario.

Per ulteriori informazioni sulla pianificazione di un percorso utilizzando un token di percorso, consulta Richiedere 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 di 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 da utilizzare con l'SDK Navigation quando possibile.

• Scegliere il percorso migliore da utilizzare per l'SDK Navigation. Se richiedi token di percorso quando generi itinerari nell'API Routes, ricevi un token di percorso per ogni itinerario generato. Puoi quindi scegliere il token per l'itinerario che vuoi utilizzare quando lo passi all'SDK Navigation.

• Stima il prezzo in anticipo, incluse le stime per l'ETA e la distanza. Sebbene il costo e il tempo effettivi possano variare, questa stima riduce il divario tra il costo previsto e quello effettivo dell'itinerario.

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

Suggerimento :un token di percorso è valido per un'origine e una destinazione specifiche e in un determinato momento. 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 percorso

Puoi utilizzare l'API Routes, l'API Routes Preferred o l'API Route Optimization per pianificare un itinerario utilizzando gli obiettivi dell'itinerario. Puoi trasferire un token di percorso restituito da una di queste API all'SDK Navigation per guidare il percorso del tuo 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 restituiscono un token di percorso criptato che include la polilinea del percorso e gli obiettivi del percorso.

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

3. L'SDK Navigation recupera l'itinerario oppure, se non è disponibile a causa di condizioni in evoluzione, recupera l'itinerario più corrispondente.

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

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

Perché un percorso pianificato potrebbe non essere seguito esattamente

Considera l'itinerario pianificato e gli obiettivi dell'itinerario come linee guida da seguire: non sono prescrittivi. Potresti notare una differenza tra l'itinerario pianificato e quello fornito dalla navigazione guidata a causa di differenze nelle condizioni stradali, nella posizione di partenza o in altri parametri che sono cambiati da quando hai creato l'itinerario pianificato. Questa differenza potrebbe causare una mancata corrispondenza tra gli obiettivi pianificati e quelli effettivi per distanza e orario di arrivo stimato, tra le altre importanti qualità del viaggio.

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

Pianificare 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 Calcolare un percorso e Richiedere un token di percorso.

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

   • API Route Optimization: optimizeTours o batchOptimizeTours. Per saperne di più sulla richiesta di un token di percorso nell'API Route Optimization, consulta Transizione delle polilinee e dei 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 travel_mode su DRIVING o TWO_WHEELER
   • Imposta routing_preference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL
   • NON utilizzare Via waypoint

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

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

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

   Esempio di token di percorso 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 itinerario, richiedi un nuovo token di itinerario.

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

Per ulteriori informazioni su questo metodo, consulta Navigator.setDestinations.

Esempio

Il seguente esempio di codice 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);

Come interagiscono i token di percorso e l'SDK Navigation

Ecco come interagiscono la route generata dall'SDK Navigation e la route pianificata nel token di route:

• Sostituisce le destinazioni impostate in precedenza.

• Utilizza la posizione di partenza del veicolo.

• Si adatta alle condizioni stradali e del traffico. Scopri perché un percorso pianificato potrebbe non essere seguito esattamente.

• Ignora le seguenti opzioni relative al routing in quanto non necessarie:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• Nuovi follower:

  • Opzioni relative alle tappe, ad esempio la preferenza per il lato della strada.

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