Generare percorsi e orari di arrivo stimati per veicoli di grandi dimensioni

Destinatari della guida:leggi questa guida se sei uno sviluppatore che crea servizi per la pianificazione e l'esecuzione di percorsi utilizzando camion o altri veicoli di grandi dimensioni. I casi d'uso pertinenti includono il calcolo di tempi di percorrenza e distanze, il calcolo degli orari di arrivo stimati o la generazione di percorsi che verranno utilizzati da un'applicazione di navigazione.

Cosa tratta questa guida: questa guida spiega come utilizzare l'API Routes con il routing di veicoli di grandi dimensioni per richiedere percorsi, distanza di viaggio, tempo di percorrenza previsto e orari di arrivo stimati che tengono conto degli attributi specifici di un veicolo di grandi dimensioni, come un camion commerciale o un autobus passeggeri.

Per informazioni su come eseguire calcoli a livello di parco veicoli per veicoli di grandi dimensioni utilizzando l'API Route Optimization, consulta la documentazione relativa al routing dei camion di Route Optimization.

Obiettivi didattici

Imparerai a:

• Crea una richiesta di routing valida.
• Specifica le informazioni sul veicolo reale utilizzando dimensioni, peso e altre caratteristiche.
• Interpreta la risposta, inclusi il token del percorso e i flag di sicurezza del viaggio.

Prerequisiti

1. Il tuo progetto Google Cloud deve essere creato e l'API Routes deve essere abilitata.
2. Il tuo progetto deve essere predisposto per il routing di veicoli di grandi dimensioni. Il routing per veicoli di grandi dimensioni è disponibile per un gruppo limitato di clienti. Contattaci per richiedere l'accesso.

Limitazioni

Prima di iniziare, devi essere a conoscenza delle seguenti limitazioni e dei seguenti requisiti.

• Disponibilità geografica: il routing per veicoli di grandi dimensioni è disponibile nei 48 Stati Uniti contigui (disponibilità generale) e in Giappone (sperimentale). Non è disponibile in Alaska, alle Hawaii o nei territori degli Stati Uniti.
• Avvisi e sicurezza per i conducenti. I conducenti non devono fare affidamento esclusivamente sui percorsi restituiti da questa API per garantire la sicurezza o la legalità. Non è garantito che i percorsi siano adatti al veicolo e seguirli potrebbe esporre i conducenti a pericoli come ponti bassi o strade in cui è vietato il transito di veicoli di grandi dimensioni.
• Route best-effort. In alcuni casi, l'API non riesce a trovare un percorso che rispetti completamente le limitazioni di viaggio. Restituisce invece un percorso "best effort" che potrebbe comunque attraversare aree con limitazioni. La risposta dell'API Routes segnala chiaramente questi percorsi nel campo routeRestrictionsPartiallyIgnored. In questi casi, pianifica attentamente il percorso, idealmente utilizzando altre origini dati. Non utilizzare un percorso segnalato come Single Source Of Truth per la pianificazione o la navigazione.
• Funzionalità non supportate: il routing per veicoli di grandi dimensioni non supporta quanto segue:
  • Prezzi dei pedaggi per i camion
  • Limiti di velocità
  • Percorsi per materiali radioattivi pericolosi
• Limiti di utilizzo: tutte le richieste sono soggette ai limiti standard di query al secondo (QPS).

Crea una richiesta di percorso per camion

Per ottenere un percorso per camion, invia una richiesta HTTPS a un endpoint dell'API Routes con parametri specifici che descrivono il tuo veicolo. I concetti di questa sezione si applicano alle richieste di percorso singolo e di matrice di percorsi.

Endpoint

Puoi utilizzare due endpoint per il calcolo dei percorsi per i camion:

• computeRoutes: calcola un singolo percorso tra un'origine e una destinazione.
• computeRouteMatrix: calcola la distanza e la durata per una matrice di origini e destinazioni, ma non restituisce una polilinea del percorso.

Parametri di richiesta chiave

Nel corpo della richiesta, devi includere i seguenti parametri per attivare il routing dei camion:

• travelMode: imposta questo valore su TRUCK.
• routingPreference: imposta questo valore su TRAFFIC_AWARE_OPTIMAL.
• routeModifiers: questo oggetto contiene l'oggetto vehicleInfo in cui definisci gli attributi del veicolo. L'oggetto vehicleInfo è descritto in dettaglio di seguito.

Specifica gli attributi del veicolo

Per inviare una richiesta, devi fornire un corpo della richiesta con un oggetto vehicleInfo che descrive il veicolo. Considera queste informazioni come una specifica che corrisponde ai dettagli fisici del tuo veicolo reale. Il servizio richiede questi dettagli per restituire percorsi che tengono conto delle limitazioni stradali in base agli attributi del veicolo.

Misurazioni del veicolo

Fornisci il peso del veicolo in chilogrammi e le dimensioni del veicolo in millimetri, come indicato dai nomi dei campi. Ad esempio, l'altezza totale deve essere fornita in millimetri (totalHeightMm). Poiché le dimensioni dei camion sono spesso espresse in piedi o metri, potrebbe essere necessaria una conversione delle unità.

Conversione dal sistema imperiale a quello metrico

Quando converti le unità imperiali, considera sempre le dimensioni specifiche del tuo veicolo insieme ai limiti di dimensioni standard di strade e sottopassaggi. Questo può essere particolarmente importante con i valori frazionari. A seconda delle dimensioni effettive del veicolo, l'arrotondamento per eccesso di un valore frazionario può comportare un percorso eccessivamente restrittivo per il veicolo.

Ad esempio:

• Larghezza: molti rimorchi statunitensi hanno una larghezza di 8' 6", che corrisponde a 2590,8 mm. Arrotondando per eccesso a 2591 mm,il veicolo risulterebbe più grande di 8' 6", il che lo classificherebbe come veicolo di grandi dimensioni sulle strade degli Stati Uniti. In questo modo, il percorso verrebbe calcolato in base a vincoli significativamente diversi da quelli previsti.
• Altezza: un percorso che passa sotto un ponte di 3,35 m non è adatto a un tipico autoarticolato con un'altezza di 4,11 m. Tuttavia, i furgoni più piccoli, di circa 3 metri, potrebbero passare sotto il sottopassaggio. Di conseguenza, è fondamentale specificare con precisione gli attributi del veicolo.

Di seguito è riportato uno snippet di codice che mostra un oggetto vehicleInfo di esempio:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo campi oggetto

La tabella seguente mostra tutte le definizioni di veicoli e carichi che puoi inviare con la richiesta.

Utilizza le maschere di campo

Per ottenere risultati ottimali, includi l'intestazione X-Goog-FieldMask nella richiesta per specificare esattamente i campi che vuoi nella risposta. Le maschere di campo riducono la latenza e ti assicurano di ricevere campi di suggerimenti importanti. Come minimo, includi sempre routes.travelAdvisory.routeRestrictionsPartiallyIgnored nella maschera di campo, poiché indica se il percorso presenta una o più limitazioni che si applicano al tuo veicolo.

Per maggiori dettagli su FieldMask con l'API Routes, consulta questo articolo.

Pedaggi

Per preferire i percorsi senza pedaggio, specifica avoidTolls nella proprietà routeModifiers di una richiesta. Per ulteriori informazioni sui modificatori di percorso, consulta Specifica le caratteristiche del percorso da evitare.

La specifica di avoidTolls non garantisce percorsi senza pedaggio nella risposta. In alcuni casi, l'utilizzo di una strada a pedaggio è obbligatorio per spostarsi tra l'origine e la destinazione. Se includi routes.warnings nella maschera di campo della richiesta API Routes, i percorsi contenenti strade a pedaggio verranno annotati di conseguenza in questo campo.

Altri comportamenti di routing

Quando imposti travelMode su TRUCK, l'API ottimizza automaticamente il percorso per la manovrabilità dei veicoli di grandi dimensioni. I percorsi generati evitano le inversioni a U e preferiscono di gran lunga le autostrade alle strade più piccole. Non è necessario impostare parametri o modificatori aggiuntivi per attivare questi comportamenti.

Calcola un singolo percorso con computeRoutes

Utilizza l'endpoint computeRoutes per calcolare un percorso specifico per i camion tra un'origine e una destinazione.

Esempio di richiesta computeRoutes

Ecco una richiesta curl completa per un tipico autotreno. Questo esempio include l'endpoint, le intestazioni e il corpo della richiesta.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Esempio di risposta computeRoutes

Questa è una risposta di esempio per la richiesta precedente mostrata sopra. Tieni presente che nell'oggetto travelAdvisory il flag routeRestrictionsPartiallyIgnored non è incluso. Ciò indica che il percorso non è segnalato e si ritiene che sia completamente conforme agli attributi del veicolo.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Interpreta la risposta di computeRoutes

Una richiesta riuscita all'endpoint computeRoutes restituisce un oggetto di risposta JSON contenente uno o più percorsi possibili.

Campi di risposta chiave

• Geometria del percorso codificata: routes.polyline. Può essere utilizzato per visualizzare il percorso su una mappa.
• Durata stimata del percorso: routes.duration (in secondi). La durata del percorso per i veicoli di grandi dimensioni utilizza un nuovo modello addestrato sulle velocità di viaggio osservate dei camion reali sulla rete stradale. Può anche essere utilizzato per calcolare l'orario di arrivo stimato aggiungendo la durata stimata del viaggio all'orario di partenza previsto.
• Distanza totale del percorso: routes.distanceMeters (in metri).
• Token di route: routes.routeToken. Si tratta di un token opaco che rappresenta il percorso esatto calcolato. Passi questo token all'SDK Navigation per assicurarti che al conducente venga mostrato lo stesso percorso specifico per i camion. Per maggiori dettagli, consulta le guide dell'SDK Navigation per Android o iOS.

Controlla i flag di sicurezza del percorso

Quando ricevi una risposta, la prima cosa da fare è controllare i flag di sicurezza del percorso. Se un percorso fornito contiene una o più limitazioni che lo rendono inadatto al veicolo, il campo travelAdvisory.routeRestrictionsPartiallyIgnored sarà impostato su true.

Questo campo funge da flag per rispondere alla domanda: "Questo percorso è contrassegnato per un potenziale problema?"

• false(o omesso dalla risposta): il percorso non è contrassegnato. Il sistema ha trovato un percorso che si ritiene sia completamente conforme ai parametri forniti nella richiesta.
• true: la route è segnalata. Il sistema non è riuscito a trovare un percorso completamente conforme e ha restituito un percorso "best effort" che potrebbe non essere sicuro o legale. Questo percorso deve essere utilizzato con estrema cautela.

Calcola una matrice di percorsi (computeRouteMatrix)

Utilizza l'endpoint computeRouteMatrix per confrontare in modo efficiente i tempi di percorrenza e le distanze tra molte origini e destinazioni. Ad esempio, potresti utilizzarlo per trovare il camion più vicino a una nuova località di ritiro. Una volta identificata l'origine del veicolo che vuoi utilizzare per il tuo scopo, puoi inviare una richiesta computeRoutes per ottenere i dettagli del percorso e il token del percorso per il veicolo proposto.

Per utilizzare computeRouteMatrix, specifica vehicleInfo all'interno di ogni oggetto origin anziché nella radice della richiesta.

Esempio di richiesta computeRouteMatrix

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Esempio di risposta computeRouteMatrix

La risposta è un array in cui ogni oggetto contiene la durata e la distanceMeters per una coppia di origine e destinazione.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Passaggi successivi

• Fornisci la navigazione passo passo: scopri come utilizzare routeToken nell'SDK Navigation per Android o iOS.
• Esegui l'ottimizzazione a livello di parco veicoli: utilizza l'API Route Optimization con routing per veicoli di grandi dimensioni.
• Riferimento API: per un elenco completo di tutti i campi e i valori possibili, consulta il Riferimento API Routes.