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

A chi è rivolta questa guida: leggi questa guida se sei uno sviluppatore che crea servizi per la pianificazione e l'esecuzione di viaggi utilizzando camion o altri veicoli di grandi dimensioni. I casi d'uso pertinenti includono il calcolo dei tempi di percorrenza e delle distanze, il calcolo dei tempi di arrivo stimati o la generazione di itinerari che verranno utilizzati da un'applicazione di navigazione.

Contenuto di questa guida:questa guida spiega come utilizzare l'API Routes con Large Vehicle Routing per richiedere itinerari, distanza di viaggio, tempo di viaggio 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 per passeggeri.

Per informazioni su come eseguire calcoli a livello di flotta 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 un profilo del veicolo per il tuo veicolo reale, utilizzando dimensioni, peso e altre caratteristiche.
  • Interpretare 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 provisionato per il routing per veicoli di grandi dimensioni. Contatta il tuo rappresentante di Google per completare questo passaggio.

Limitazioni

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

  • Disponibilità geografica: il calcolo del percorso per veicoli di grandi dimensioni è disponibile solo nei 48 stati contigui degli Stati Uniti.
  • Il routing per veicoli di grandi dimensioni è un'offerta in fase di anteprima. Gli autisti non devono fare affidamento esclusivamente sugli itinerari restituiti da questa API per essere sicuri o legali. Non è garantito che gli itinerari siano adatti al veicolo e seguirli potrebbe esporre i conducenti a pericoli come ponti bassi o strade in cui sono vietati i veicoli di grandi dimensioni.
  • Itinerari con il massimo sforzo. In alcuni casi, l'API non riesce a trovare un itinerario che rispetti pienamente le restrizioni di viaggio. Restituisce invece un percorso "best effort" che potrebbe comunque attraversare aree con limitazioni. La risposta dell'API Routes contrassegna chiaramente questi percorsi nel campo routeRestrictionsPartiallyIgnored. In questi casi, pianifica attentamente il percorso, idealmente utilizzando altre origini dati. Non utilizzare un percorso segnalato come unica fonte attendibile per la pianificazione o la navigazione.
  • Funzionalità non supportate: stiamo lavorando per aggiungere altre funzionalità a questa offerta, ma il calcolo del percorso per veicoli di grandi dimensioni non supporta le seguenti funzionalità:
    • Prezzi dei pedaggi per i camion
    • Limiti di velocità
    • Itinerario per materiali pericolosi radioattivi
  • Limiti di utilizzo:tutte le richieste sono soggette ai limiti standard di query al secondo (QPS).

Crea una richiesta di itinerario per camion

Per ottenere un itinerario per camion, invia una richiesta HTTPS a un endpoint dell'API Routes con parametri specifici che descrivono il tuo veicolo.

Endpoint

Puoi utilizzare due endpoint per il calcolo dell'itinerario per i camion:

  • computeRoutes: calcola un'unica route 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 dell'itinerario.

Parametri di richiesta della chiave

Nel corpo della richiesta, devi includere quanto segue:

  • 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 tuo veicolo. L'oggetto vehicleInfo è descritto in dettaglio di seguito.

Specificare un profilo del veicolo

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

Misure 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 del camion sono spesso espresse in piedi o metri, potrebbe essere necessaria una conversione delle unità.

Conversione da sistema imperiale a sistema metrico

Quando esegui la conversione dalle unità imperiali, considera sempre le dimensioni specifiche del tuo veicolo insieme ai limiti standard di dimensioni di strade e sottopassaggi. Questo può essere particolarmente importante con i valori frazionari. A seconda delle dimensioni del veicolo effettivo, 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", ovvero 2590,8 mm. L'arrotondamento a 2591 mm indicherebbe che il veicolo è più grande di 259 cm, il che lo classificherebbe come veicolo fuori misura sulle strade statunitensi. Ciò comporterebbe un percorso calcolato in base a vincoli significativamente diversi da quelli previsti.
  • Altezza: un percorso che passa sotto un ponte di 3,35 metri non sarebbe adatto a un tipico autoarticolato con un'altezza di 4,11 metri. Tuttavia, i furgoni più piccoli di circa 3 metri potrebbero passare sotto il cavalcavia. Di conseguenza, è fondamentale specificare con precisione gli attributi del veicolo.

Un diagramma che illustra le dimensioni di un camion rispetto a quelle di un sottopassaggio

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

"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 veicolo e carico che puoi inviare con la richiesta.

Campo Descrizione Note / valori
totalHeightMm L'altezza massima del veicolo. In millimetri, arrotondato per difetto. Per ulteriori dettagli sull'arrotondamento, consulta Conversione da sistema imperiale a sistema metrico.
totalWidthMm La larghezza massima del veicolo. In millimetri, arrotondato per difetto.
totalLengthMm La lunghezza totale combinata del veicolo e di eventuali rimorchi. In millimetri, arrotondato per difetto.
totalWeightKg Il peso lordo del veicolo (inclusi rimorchi e carico). In chilogrammi, arrotondato per difetto.
totalAxleCount Il numero totale di assi del veicolo e di eventuali rimorchi. Esatto.
trailerInfo (facoltativo) Un array di oggetti, uno per ogni trailer. Ometti per un veicolo senza rimorchi, come un furgone.
hazardousGoodsTypes (facoltativo) Un array che specifica eventuali materiali pericolosi a bordo. ESPLOSIVI, GAS, INFIAMMABILI, COMBUSTIBILI, ORGANICI, VELENI, CORROSIVI, PERICOLO_ASPIRAZIONE, PERICOLO_AMBIENTALE, ALTRO

Utilizzare le maschere dei campi

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

Per ulteriori dettagli sulle maschere di campo 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 Specificare le caratteristiche del percorso da evitare.

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

Esempio di richiesta curl completa

Ecco una richiesta curl completa per un tipico autoarticolato. 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
      }]
    }
  }
}'

Interpretare la risposta di computeRoutes

Una richiesta riuscita all'API Routes restituisce un oggetto risposta JSON contenente uno o più percorsi possibili.

Campi di risposta chiave

  • Geometria dell'itinerario codificata: routes.polyline. Può essere utilizzato per visualizzare il percorso su una mappa.
  • Durata stimata del viaggio: routes.duration (in secondi). La durata del viaggio per il calcolo dell'itinerario per veicoli di grandi dimensioni utilizza un nuovo modello addestrato sulle velocità di viaggio osservate di camion reali sulla rete stradale. Può essere utilizzato anche 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 percorso: routes.routeToken. Si tratta di un token opaco che rappresenta l'itinerario calcolato esatto. Passa questo token all'SDK Navigation per assicurarti che al conducente venga mostrato lo stesso percorso specifico per i camion. Per maggiori dettagli su come eseguire questa operazione, consulta la guida Fornire indicazioni stradali passo passo.

Controllare i flag di sicurezza del percorso

Quando ricevi una risposta, la prima cosa da fare è controllare la presenza di indicatori di sicurezza dell'itinerario. Se un percorso fornito contiene una o più limitazioni che lo rendono non adatto al veicolo, il campo travelAdvisory.routeRestrictionsPartiallyIgnored è impostato su true.

Questo campo funge da indicatore per rispondere alla domanda: "Questo percorso è stato segnalato per un potenziale problema?"

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

Esempio: risposta computeRoutes

Questa è una risposta di esempio per la richiesta mostrata sopra. Tieni presente che nell'oggetto travelAdvisory il flag routeRestrictionsPartiallyIgnored non è incluso. Ciò indica che l'itinerario non è contrassegnato e si ritiene che sia completamente conforme al profilo del veicolo.

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

Ottenere una matrice di itinerari per camion

Per calcolare i tempi di percorrenza per molti potenziali viaggi contemporaneamente, utilizza l'endpoint computeRouteMatrix per la pianificazione di alto livello 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 un nuovo luogo 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 origine.

Esempio di richiesta

{
  "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

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

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

Passaggi successivi