Pianificare un percorso

A volte potresti voler pianificare il percorso fornito dalla tua app 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

• Scopi del percorso

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

• Riduci al minimo i tempi di consegna: un'attività che consegna cibo potrebbe voler minimizzare i tempi di consegna.

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

• Riduci al minimo il tempo di percorrenza: un'operazione di invio di servizi potrebbe voler minimizzare il tempo necessario per far arrivare gli operatori a una richiesta di lavoro.

• Ridurre i costi e migliorare la sicurezza: un'azienda 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 effettivo percorso può variare da quello pianificato fornito dal token. Il traffico in mutazione, le condizioni stradali o la deviazione del veicolo dal percorso indicato possono comportare modifiche al percorso. Quando si verificano modifiche, l'SDK Navigation tenta continuamente di tornare al percorso pianificato oppure, se il ritorno non è pratico, segue gli obiettivi del percorso nel token percorso.

Per ulteriori informazioni sulla pianificazione di un itinerario utilizzando un token itinerario, consulta Richiedi un token itinerario nell'API Routes e Trasferimento di polilinee e token itinerario nell'API Route Optimization.

Perché utilizzare un token route per gli scopi della route

Con un token 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 da parte dell'SDK Navigation, se possibile.

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

• Stimare il prezzo in anticipo, incluse le stime per l'orario di arrivo stimato e la distanza. Anche se il costo e il tempo effettivi potrebbero variare, questa stima riduce la differenza tra il costo previsto e quello effettivo del percorso.

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

Suggerimento: un token percorso è destinato a una stazione di partenza e una di destinazione specifiche e a un determinato orario. Devi effettuare una nuova richiesta per un nuovo token percorso con l'API Routes, con l'API Routes Preferred o con l'API Route Optimization.

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 scopi del percorso. Puoi passare un token percorso restituito da una di queste API all'SDK Navigation per indicare il percorso del veicolo.

Ecco cosa succede quando richiedi e utilizzi un token percorso:

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

2. Trasmetti il token percorso all'SDK Navigation.

3. L'SDK Navigation recupera il percorso oppure, se non è disponibile a causa di condizioni mutevoli, recupera il percorso con la migliore corrispondenza.

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 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 il percorso pianificato e gli 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 cambiati da quando hai creato il percorso pianificato. Questa differenza potrebbe comportare una mancata corrispondenza tra gli scopi pianificati e quelli effettivi per distanza e orario di arrivo stimato, tra le altre qualità importanti del viaggio.

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

Pianificare un percorso utilizzando un token percorso

Puoi pianificare un itinerario creando un token itinerario e poi passandolo all'SDK Navigation, come descritto nei passaggi che seguono:

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

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

   • API Routes: computeRoutes. Per ulteriori informazioni su come richiedere un token percorso nell'API Routes, consulta Calcolo di un percorso e Richiesta di un token percorso.

   • API Routes Preferred: computeCustomRoutes. Per ulteriori informazioni su come richiedere un token percorso nell'API Routes Preferred, consulta Pianificare un percorso.

   • API Route Optimization: optimizeTours o batchOptimizeTours. Per saperne di più su come richiedere un token percorso nell'API Route Optimization, consulta Trasferimento di polilinee e token percorso.

2. Configura la richiesta dell'API Routes o dell'API Routes Preferred per soddisfare i requisiti per l'utilizzo di un token 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 percorso all'SDK Navigation

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

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

   Esempio di token percorso restituito:

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

2. Passa il token percorso all'SDK Navigation utilizzando il metodo Navigator.setDestinations, specificando gli stessi waypoint di destinazione che hai utilizzato per creare il token 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 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 un itinerario pianificato utilizzando un token itinerario.

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

Interazione tra i token route e l'SDK Navigation

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

• Sostituiscono le destinazioni impostate in precedenza.

• Utilizza la posizione di partenza del veicolo.

• Si regola in base alle condizioni stradali e del traffico. Consulta Perché un percorso pianificato potrebbe non essere seguito esattamente.

• Ignora le seguenti opzioni relative al routing perché non necessarie:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• Seguiti:

  • Opzioni relative ai waypoint, ad esempio la preferenza per il lato della strada.

  • Obiettivi del percorso. Se l'SDK di navigazione deve aggiustare il percorso restituito, utilizza gli scopi del percorso specificati al momento della richiesta del token del percorso. Per questo motivo, devi utilizzare le stesse opzioni relative ai punti di passaggio che hai specificato nell'API Routes.