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

A chi si rivolge 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 degli orari di arrivo stimati o la generazione di itinerari che verranno utilizzati da un'applicazione di navigazione.

Cosa tratta questa guida:questa guida spiega come utilizzare l'API Routes con l'itinerario per veicoli di grandi dimensioni per richiedere itinerari, distanza di viaggio, tempo di percorrenza previsto e orari di arrivo stimati che tengano 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 risorse per veicoli di grandi dimensioni utilizzando l'API Route Optimization, consulta la documentazione relativa al calcolo itinerario per camion dell'API Route Optimization.

Obiettivi didattici

Imparerai a:

  • Creare una richiesta di itinerario valida.
  • Specificare le informazioni sul veicolo per il tuo veicolo reale, utilizzando dimensioni, peso e altre caratteristiche.
  • Interpretare la risposta, inclusi il token dell'itinerario e gli indicatori di sicurezza del viaggio.

Prerequisiti

  1. Il progetto Google Cloud deve essere creato e l'API Routes deve essere abilitata.
  2. Il progetto deve essere provisionato per l'itinerario per veicoli di grandi dimensioni. L'itinerario per veicoli di grandi dimensioni è disponibile per un insieme limitato di clienti. Contattaci per richiedere l'accesso

Limitazioni

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

  • Disponibilità geografica: l'itinerario per veicoli di grandi dimensioni è disponibile nei 48 stati contigui degli Stati Uniti (disponibilità generale) e Giappone (sperimentale). Non è disponibile in Alaska, Hawaii o nei territori degli Stati Uniti.
  • Avvisi e sicurezza per i conducenti. I conducenti 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, se li seguono, i conducenti potrebbero essere esposti a pericoli come ponti bassi o strade in cui i veicoli di grandi dimensioni sono vietati.
  • Itinerari con il criterio del "best effort". In alcuni casi, l'API non riesce a trovare un itinerario che rispetti completamente le limitazioni di viaggio. Restituisce invece un itinerario con il criterio del "best effort" che potrebbe comunque attraversare aree con limitazioni. La risposta dell'API Routes contrassegna chiaramente questi itinerari nel campo routeRestrictionsPartiallyIgnored. In questi casi, pianifica attentamente l'itinerario, idealmente utilizzando altri dati di origine. Non utilizzare un itinerario contrassegnato come unica fonte attendibile per la pianificazione o la navigazione.
  • Funzionalità non supportate: l'itinerario per veicoli di grandi dimensioni non supporta le seguenti funzionalità:
    • Prezzi dei pedaggi per 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).

Creare 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. I concetti descritti in questa sezione si applicano sia alle richieste di itinerario singolo sia a quelle di matrice di itinerari.

Endpoint

Puoi utilizzare due endpoint per l'itinerario per camion:

  • computeRoutes: calcola un singolo itinerario 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 principali

Nel corpo della richiesta, devi includere i seguenti parametri per attivare l'itinerario per 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 tuo veicolo. L'oggetto vehicleInfo è descritto in dettaglio di seguito.

Specificare gli attributi del veicolo

Per inviare una richiesta, devi fornire un corpo della richiesta con un oggetto vehicleInfo che descriva il tuo veicolo. Considera queste informazioni come una specifica che corrisponde ai dettagli fisici del tuo veicolo reale. Il servizio richiede questi dettagli per restituire itinerari che tengano conto delle limitazioni stradali in base agli attributi del tuo 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 di unità.

Conversione da unità imperiali a unità metriche

Quando esegui la conversione da unità imperiali, tieni sempre in considerazione 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 del veicolo effettivo, l'arrotondamento per eccesso di un valore frazionario può comportare un itinerario eccessivamente restrittivo per il veicolo.

Ad esempio:

  • Larghezza: molti rimorchi statunitensi hanno una larghezza di 8' 6", che corrisponde a 2590,8 mm. L'arrotondamento per eccesso a 2591 mm indicherebbe che il veicolo è più grande di 8' 6", il che lo classificherebbe come veicolo fuori misura sulle strade statunitensi. Di conseguenza, l'itinerario calcolato sarebbe soggetto a vincoli significativamente diversi da quelli previsti.
  • Altezza: un itinerario che passa sotto un ponte di 11' non sarebbe adatto a un tipico autoarticolato con un'altezza di 13,5'. Tuttavia, i furgoni più piccoli di circa 10' sarebbero in grado di attraversare il sottopassaggio. 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
      }

Campi dell'oggetto vehicleInfo

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

Campo Descrizione Note / valori
totalHeightMm L'altezza massima del veicolo. In millimetri, arrotondata per difetto. Per maggiori dettagli sull'arrotondamento, consulta la sezione Conversione da unità imperiali a unità metriche.
totalWidthMm La larghezza massima del veicolo. In millimetri, arrotondata per difetto.
totalLengthMm La lunghezza totale combinata del veicolo e di eventuali rimorchi. In millimetri, arrotondata 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 rimorchio. Ometti per un veicolo senza rimorchi, come un furgone.
hazardousGoodsTypes (facoltativo) Un array che specifica eventuali materiali pericolosi a bordo. EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

Utilizzare 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 i campi di avviso importanti. Come minimo, includi sempre routes.travelAdvisory.routeRestrictionsPartiallyIgnored nella maschera di campo, poiché indica se l'itinerario presenta una o più limitazioni applicabili al tuo veicolo.

Per maggiori dettagli sulle maschere di campo con l'API Routes, consulta questo articolo.

Pedaggi

Per preferire gli itinerari senza pedaggio, specifica avoidTolls nella proprietà routeModifiers di una richiesta. Per ulteriori informazioni sui modificatori di itinerario, consulta la sezione Specificare le funzionalità dell'itinerario da evitare.

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

Altri comportamenti di itinerario

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

Calcolare un singolo itinerario con computeRoutes

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

Esempio di richiesta computeRoutes

Di seguito è riportata 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
      }]
    }
  }
}'

Esempio di risposta computeRoutes

Di seguito è riportata una risposta di esempio alla richiesta precedente mostrata sopra. Tieni presente che nell'oggetto travelAdvisory non è incluso l'indicatore routeRestrictionsPartiallyIgnored. Ciò indica che l'itinerario non è contrassegnato e si ritiene che sia pienamente conforme agli attributi del veicolo.

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

Interpretare la risposta computeRoutes

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

Campi di risposta principali
  • Geometria dell'itinerario codificata: routes.polyline. Può essere utilizzata per visualizzare l'itinerario su una mappa.
  • Durata stimata del viaggio: routes.duration (in secondi). La durata del viaggio per l'itinerario per veicoli di grandi dimensioni utilizza un nuovo modello addestrato sulle velocità di viaggio osservate dei camion effettivi sulla rete stradale. Può essere utilizzata anche per calcolare l'orario di arrivo stimato aggiungendo la durata stimata del viaggio all'orario di partenza previsto.
  • Distanza totale dell'itinerario: routes.distanceMeters (in metri).
  • Token dell'itinerario: 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 itinerario specifico per camion. Per maggiori dettagli, consulta le guide dell'SDK Navigation per Android o iOS.
Controllare gli indicatori di sicurezza dell'itinerario

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

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

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

Calcolare una matrice di itinerari (computeRouteMatrix)

Utilizza l'endpoint computeRouteMatrix per confrontare in modo efficiente i tempi di percorrenza e le distanze tra molte origini e destinazioni. Ad esempio, puoi 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 dell'itinerario e il token dell'itinerario per il veicolo proposto.

Per utilizzare computeRouteMatrix, specifica vehicleInfo all'interno di ogni oggetto origin anziché alla 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 distanceMeters per una coppia origine-destinazione.

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

Passaggi successivi