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 aspetti del percorso pianificato:

Una polilinea per il percorso
I tuoi obiettivi di percorso

Ad esempio, ecco alcuni 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 la consegna.
Ridurre al minimo il tempo di percorrenza 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 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 evitare determinate aree per motivi di sicurezza.

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 dall'API Routes, dall'API Routes Preferred o dall'API Route Optimization, hai un maggiore controllo sul percorso fornito:

Pianifica un percorso in anticipo per l'SDK Navigation da utilizzare, se possibile.
Scegli il percorso migliore da utilizzare per l'SDK Navigation. Se richiedi token di percorso durante la generazione dei percorsi nell'API Routes, riceverai un token di percorso per ogni percorso generato. Puoi quindi scegliere il token per il percorso che vuoi utilizzare quando lo passi all'SDK Navigation.
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 routing ecologico o il percorso più breve.

Come funzionano i token di percorso

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

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

L'API Routes, l'API Routes Preferred o l'API Route Optimization restituisce un token di percorso criptato che include la polilinea del percorso e gli obiettivi del percorso.
Passa il token di percorso all'SDK Navigation.
L'SDK Navigation recupera il percorso o, se il percorso non è disponibile a causa delle condizioni in continua evoluzione, recupera il percorso più corrispondente.
Durante la guida sul 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 al percorso 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 il percorso 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 obiettivi pianificati ed effettivi per la distanza e l'orario di arrivo stimato, tra le altre importanti qualità del viaggio.

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

Richiedi un token di percorso con uno dei seguenti metodi:
- API Routes: computeRoutes. Per ulteriori informazioni 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 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.
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 DRIVE o TWO_WHEELER
- Imposta routing_preference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL
- NON utilizzare le tappe Via

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

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",
}

Passa il token di percorso all'SDK Navigation utilizzando il metodo Navigator.setDestinations, specificando le stesse tappe di destinazione utilizzate 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();

Il metodo Navigator.setDestinations restituisce lo stato della richiesta. Se trova un percorso dalla posizione del veicolo alla destinazione indicata, restituisce RouteStatus.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 il percorso generato dall'SDK Navigation e il percorso pianificato nel token di percorso:

Esegue l'override di tutte le destinazioni impostate in precedenza.
Utilizza la posizione di partenza del veicolo.
Si adatta 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 sono necessarie:
- avoidsHighways
- avoidsTolls
- avoidsFerries
- licensePlateRestriction
Segue:
- Opzioni relative alle tappe, come la preferenza per il lato della strada.
- Obiettivi del percorso. Se l'SDK Navigation deve modificare il percorso restituito, utilizza gli obiettivi del percorso specificati durante la richiesta del token di percorso. Per questo motivo, devi utilizzare le stesse opzioni relative alle tappe specificate nell'API Routes.