Gestire i dati sul percorso

Quando recuperi i dati sul percorso, il backend riceve payload JSON che descrivono in dettaglio l'avanzamento del viaggio del conducente. Analizza questi payload per monitorare la corsa, aggiornare i sistemi di assegnazione e interpretare gli stati attuali della corsa per determinare il passaggio successivo per il conducente man mano che procede o al termine di una corsa.

Leggi il payload dei dati

Google Maps o Waze inviano i payload dei dati sul percorso ai server di Navigation Connect quando il conducente inizia a navigare, periodicamente lungo il percorso (ogni 60 secondi per impostazione predefinita) e quando il conducente arriva a destinazione. Ogni messaggio JSON contiene i dati sul percorso pertinenti, tra cui le coordinate del conducente allineate alla strada, la distanza percorsa e l'orario di arrivo stimato (ETA). Poiché questi aggiornamenti riflettono il percorso attivo in tempo reale dell'autista, potrebbero differire dai percorsi precalcolati dal backend (vedi le domande frequenti).

Il seguente esempio di codice mostra un payload di dati sul percorso per quando un autista inizia la navigazione per un viaggio da King's Cross a Central St. Giles.

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

Monitorare gli stati delle corse attive

Per confermare l'avvio riuscito e monitorare l'avanzamento, valuta il campo state in ogni payload.

Stato Descrizione
NEW La corsa è stata creata, ma l'autista non ha ancora iniziato la navigazione.
ENROUTE Il conducente sta navigando attivamente verso la destinazione. Utilizza questo stato per confermare che la corsa è stata autenticata e avviata correttamente.

Gestire le tappe aggiunte

I conducenti possono aggiungere tappe al loro percorso durante la navigazione. In caso affermativo, Navigation Connect imposta il campo execution.stopAddedInRoute su true nel payload dei dati JSON. L'API Navigation Connect continua a monitorare l'autista verso la destinazione originale. Metriche come l'orario di arrivo stimato (ATE), la distanza e la durata aumentano per includere le tappe aggiuntive.

Il comportamento per l'aggiunta di tappe dipende dall'app di navigazione e corrisponde alla sua funzionalità standard:

  • Google Maps: i conducenti possono aggiungere più tappe al loro percorso.
  • Waze:gli autisti possono aggiungere una sola fermata. Se un autista tenta di aggiungere un'altra fermata, Waze gli chiede di avviare una nuova sessione di navigazione anziché aggiungere la fermata all'itinerario attuale.

Non è necessario modificare gli input di backend per supportare questa funzionalità.

Risolvere i problemi di autenticazione e avvio

Se non ricevi lo stato ENROUTE, probabilmente si è verificato un errore di autenticazione. Le cause comuni includono parametri API con errori ortografici o un token di viaggio scaduto. Controlla l'ora di scadenza del token nella risposta CreateTrip iniziale.

Se lo stato non cambia da NEW a ENROUTE, il dispositivo del conducente potrebbe impedire l'autenticazione. Navigation Connect non invia messaggi di errore per questi casi. Verifica quanto segue:

  • Il conducente ha installato Waze versione 5.15.5 o successive oppure Google Maps versione 26.14 o successive.
  • Il conducente non utilizza Android Auto o Apple CarPlay.
  • Il conducente ha una connessione a internet attiva.

Gestire i dati rimanenti del percorso (solo Waze)

Se hai attivato la segnalazione del percorso rimanente durante la creazione del viaggio, il backend riceve la polilinea del percorso rimanente e le condizioni del traffico in tempo reale dalla posizione attuale del conducente alla destinazione finale.

Puoi importare ed elaborare questi dati per attivare diverse funzionalità nelle tue applicazioni, inclusi i seguenti esempi:

  • Migliorare le mappe di monitoraggio in tempo reale: esegui il rendering della polilinea del percorso rimanente su una mappa web o mobile rivolta ai clienti per fornire visibilità sul viaggio del conducente.
  • Migliora l'accuratezza dell'orario di arrivo stimato: combina la polilinea agganciata alla strada e le velocità degli intervalli di traffico per migliorare le previsioni interne di logistica o di arrivo delle consegne.
  • Analizza la conformità dell'itinerario: confronta la geometria dell'itinerario rimanente con gli itinerari di spedizione previsti per valutare l'aderenza del conducente (vedi le domande frequenti per dettagli sul motivo per cui gli itinerari in tempo reale e quelli precalcolati potrebbero differire).

Navigation Connect restituisce i dettagli del percorso rimanenti nel campo execution.remainingRoute, che tu invii una richiesta GetTrip o riceva aggiornamenti basati su eventi utilizzando Google Cloud Pub/Sub. Tuttavia, il modo in cui i formati e le strutture del payload organizzano questi dati dipende dal metodo di recupero che utilizzi.

Metodo GetTrip

Quando chiami il metodo GetTrip, il formato della risposta per la polilinea dipende dal parametro routePolylineFormat specificato nella richiesta. Per saperne di più, consulta Personalizzare i formati delle polilinee.

Per tutti i formati polilinea, Navigation Connect restituisce il traffico come un elenco separato di oggetti SpeedReadingInterval nel campo execution.remainingRoute.trafficInformation. Questi oggetti mappano le categorie di traffico agli indici delle polilinee utilizzando i seguenti valori:

Aggiornamenti di Google Cloud Pub/Sub

Quando recuperi i dati sul percorso con Pub/Sub, gli aggiornamenti restituiscono sempre i dati del percorso rimanente in un GeoJSON unificato FeatureCollection nel campo execution.remainingRoute.

Questo formato combina direttamente la geometria della polilinea con le velocità del traffico, eliminando la necessità di mappare manualmente gli indici.

Visualizza un esempio di payload Pub/Sub

Il seguente esempio di codice mostra la struttura GeoJSON restituita nel campo execution.remainingRoute all'interno dell'oggetto updatedTrip di un messaggio Pub/Sub:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}

Ottimizzare le dimensioni del payload

Poiché gli array di coordinate sono grandi, l'inclusione dei dati del percorso rimanenti nei messaggi Pub/Sub può aumentare notevolmente le dimensioni del payload (fino a 13-14 KB per messaggio). Se ricevi aggiornamenti ad alta frequenza, questo volume può aumentare il carico di elaborazione backend e i costi di utilizzo.

Per ottimizzare lo stream, utilizza il parametro pubsubFieldMask nell'oggetto TripConfig durante la creazione del viaggio per escludere i campi pesanti. Per maggiori dettagli, vedi Configurazioni facoltative.

Gestire le deviazioni dall'itinerario (solo Waze)

Se hai attivato la segnalazione di deviazione dal percorso durante la creazione del viaggio, quando un autista si allontana dal percorso, l'API restituisce i metadati di deviazione dal percorso. Puoi accedere a questi dati nei seguenti modi:

  • On demand:chiama il metodo GetTrip. Il server memorizza l'ultimo stato di deviazione noto.
  • In tempo reale:abbonati a Google Cloud Pub/Sub. Il servizio pubblica aggiornamenti sulla deviazione utilizzando l'evento updated_trip esistente entro 5 secondi dal rilevamento.

Leggere il payload di deviazione

L'oggetto last_route_deviation fornisce i seguenti metadati per aiutarti ad analizzare l'evento.

Campo Tipo Descrizione
location LatLng Le coordinate di latitudine e longitudine in cui il dispositivo client ha registrato la deviazione.
source TriggerSource Il motivo della deviazione. Utilizza questo campo per determinare se il conducente ha intrapreso un'azione imprevista o ha seguito le indicazioni del sistema:
  • DRIVER_INITIATED_REROUTE: Il conducente ha fatto una scelta attiva (ad esempio, ha svoltato in modo errato o ha selezionato manualmente un nuovo percorso).
  • SYSTEM_INITIATED_REROUTE: l'app di navigazione ha calcolato un nuovo percorso (ad esempio a causa di cambiamenti nelle condizioni del traffico o chiusure stradali).
client_timestamp Timestamp L'ora in cui il dispositivo client ha rilevato la deviazione.
server_timestamp Timestamp L'ora in cui il server ha elaborato l'aggiornamento della deviazione.

Gestire gli stati di fine viaggio

Quando un conducente raggiunge la destinazione o interrompe la navigazione, il payload restituisce uno dei seguenti stati finali. Utilizza questi stati per attivare i passaggi successivi appropriati nella tua app.

Stato Descrizione Azione consigliata
ARRIVED L'autista ha raggiunto la destinazione. Controlla remainingDistanceMeters. Se l'autista ha parcheggiato nelle vicinanze, ma non alle coordinate esatte, valuta la possibilità di fornire indicazioni a piedi nella tua app.
SUSPENDED L'autista è uscito manualmente dalla navigazione passo passo prima di arrivare a destinazione.
Poiché Google Maps o Waze non riportano automaticamente i conducenti alla tua app quando escono da una sessione in anticipo, il conducente deve toccare manualmente il pulsante di ritorno. 		Per aiutare i conducenti a completare il viaggio, confronta execution.location con la destinazione. Se la distanza rimane, fornisci un pulsante o un link per riprendere il viaggio o passare alla modalità a piedi.
FAILED Un errore tecnico ha interrotto la connessione. Ciò si verifica se l'app non riesce a calcolare un percorso o viene visualizzato un avviso di sicurezza. Il conducente potrebbe continuare a navigare, ma non riceverai aggiornamenti. Ripiega sul monitoraggio manuale dello stato nell'app.
CLIENT_ERROR Questo stato viene visualizzato per uno dei seguenti motivi:
  • Il conducente revoca il consenso.
  • Il conducente utilizza una piattaforma non supportata, come Android Auto o Apple CarPlay.
  • La tua app riutilizza un token di viaggio in viaggi separati. Ad esempio, Navigation Connect rifiuta le richieste che modificano la destinazione di un viaggio o aggiornano un viaggio completato.
  • Il conducente si trova negli Stati Uniti in qualsiasi momento del viaggio, ma la condivisione dei dati negli Stati Uniti non è attivata nella tua app quando hai verificato l'app durante la configurazione.
 Ripiega sul monitoraggio manuale dello stato nell'app.