Lorsque vous récupérez les données de votre trajet, votre backend reçoit des charges utiles JSON détaillant la progression du trajet du conducteur. Analysez ces charges utiles pour surveiller le trajet, mettre à jour vos systèmes de répartition et interpréter les états actuels du trajet afin de déterminer la prochaine étape pour le conducteur au fur et à mesure de sa progression ou à la fin du trajet.
Lire la charge utile de données
Google Maps ou Waze envoie les charges utiles de données de trajet aux serveurs Navigation Connect lorsque le conducteur commence la navigation, périodiquement le long de l'itinéraire (toutes les 60 secondes par défaut) et lorsqu'il arrive à destination. Chaque message JSON contient des données de trajet pertinentes, y compris les coordonnées du conducteur sur la route, la distance parcourue et l'heure d'arrivée prévue.
L'exemple de code suivant montre une charge utile de données de trajet lorsqu'un conducteur commence la navigation pour un trajet de King's Cross à 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
}
}
Surveiller les états de trajet actifs
Pour confirmer le démarrage et surveiller la progression, évaluez le champ d'état dans chaque charge utile.
| État | Description |
|---|---|
NEW |
Le trajet est créé, mais le conducteur n'a pas encore commencé la navigation. |
ENROUTE |
Le conducteur est en train de se rendre à destination. Utilisez cet état pour confirmer que le trajet a été authentifié et a démarré correctement. |
Gérer les arrêts ajoutés
Les conducteurs peuvent ajouter des arrêts à leur itinéraire pendant la navigation. Dans ce cas, Navigation Connect définit le champ execution.stopAddedInRoute sur true dans la charge utile de données JSON. L'API Navigation Connect continue de suivre le conducteur vers la destination d'origine. Les métriques telles que l'heure d'arrivée prévue, la distance et la durée augmentent pour inclure les arrêts ajoutés.
Le comportement d'ajout d'arrêts dépend de l'application de navigation et correspond à sa fonctionnalité standard :
- Google Maps : les conducteurs peuvent ajouter plusieurs arrêts à leur itinéraire.
- Waze : les conducteurs ne peuvent ajouter qu'un seul arrêt. Si un conducteur tente d'ajouter un autre arrêt, Waze l'invite à démarrer une nouvelle session de navigation au lieu d'ajouter l'arrêt à l'itinéraire actuel.
Vous n'avez pas besoin d'ajuster les entrées de votre backend pour prendre en charge cette fonctionnalité.
Résoudre les problèmes d'authentification et de démarrage
Si vous ne recevez pas l'état ENROUTE, une erreur d'authentification s'est probablement produite. Les causes courantes incluent des paramètres d'API mal orthographiés ou un jeton de trajet expiré. Vérifiez l'heure d'expiration du jeton dans votre réponse CreateTrip initiale.
Si l'état ne passe pas de NEW à ENROUTE, l'appareil du conducteur peut empêcher l'authentification. Navigation Connect n'envoie pas de messages d'erreur dans ces cas. Effectuez les vérifications suivantes :
- La version 5.15.5 ou ultérieure de Waze, ou la version 26.14 ou ultérieure de Google Maps est installée sur l'appareil du conducteur.
- Le conducteur n'utilise pas Android Auto ni Apple CarPlay.
- Le conducteur dispose d'une connexion Internet active.
Gérer les données d'itinéraire restantes (Waze uniquement)
Si vous avez activé la création de rapports sur l'itinéraire restant lors de la création du trajet, votre backend reçoit la polyligne d'itinéraire active et les conditions de trafic en temps réel depuis la position actuelle du conducteur jusqu'à sa destination finale.
Vous pouvez ingérer et traiter ces données pour alimenter plusieurs fonctionnalités de vos applications, y compris les exemples suivants :
- Alimenter les cartes de suivi en direct : affichez la polyligne d'itinéraire restante sur une carte Web ou mobile destinée aux clients pour leur permettre de suivre le trajet du conducteur.
- Améliorer la précision de l'heure d'arrivée prévue : combinez la polyligne sur la route et les vitesses d'intervalle de trafic pour améliorer la logistique interne ou les prévisions d'arrivée des livraisons.
- Analyser la conformité de l'itinéraire : comparez la géométrie de l'itinéraire restant aux itinéraires de répartition prévus pour évaluer le respect des itinéraires par le conducteur.
Navigation Connect renvoie les détails de l'itinéraire restant dans le champ execution.remainingRoute, que vous envoyiez une requête GetTrip ou que vous receviez des mises à jour basées sur des événements à l'aide de Google Cloud Pub/Sub. Toutefois, la façon dont la charge utile met en forme et structure ces données dépend de la méthode de récupération que vous utilisez.
Méthode GetTrip
Lorsque vous appelez la méthode GetTrip, le format de réponse de la polyligne dépend du paramètre routePolylineFormat que vous avez spécifié dans votre requête. Pour en savoir plus, consultez Personnaliser les formats de polyligne.
Pour tous les formats de polyligne, Navigation Connect renvoie le trafic sous la forme d'une liste distincte d'objets SpeedReadingInterval dans le champ execution.remainingRoute.trafficInformation. Ces objets associent les catégories de trafic aux index de polyligne à l'aide des valeurs suivantes :
startPolylinePointIndex: index de départ de l'intervalle de trafic sur la polyligne.endPolylinePointIndex: index de fin de l'intervalle de trafic.speed: catégorie de trafic pour ce segment :NORMAL,SLOWouTRAFFIC_JAM.
Mises à jour Google Cloud Pub/Sub
Lorsque vous récupérez des données de trajet avec Pub/Sub,
les mises à jour renvoient toujours les données d'itinéraire restantes dans un GeoJSON unifié
FeatureCollection dans le champ execution.remainingRoute.
Ce format combine directement la géométrie de la polyligne avec les vitesses de trafic, ce qui évite d'avoir à mapper manuellement les index.
Consulter un exemple de charge utile Pub/Sub
L'exemple de code suivant montre la structure GeoJSON renvoyée dans le champ execution.remainingRoute de l'objet updatedTrip d'un message 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" } } ] }
Optimiser la taille de la charge utile
Étant donné que les tableaux de coordonnées sont volumineux, l'inclusion des données d'itinéraire restantes dans vos messages Pub/Sub peut augmenter considérablement la taille de la charge utile (jusqu'à 13 à 14 Ko par message). Si vous recevez des mises à jour à haute fréquence, ce volume peut augmenter la charge de traitement du backend et les coûts d'utilisation.
Pour optimiser votre flux, utilisez le paramètre pubsubFieldMask dans votre objet TripConfig lors de la création du trajet afin d'exclure les champs volumineux. Pour
en savoir plus, consultez Configurations facultatives.
Gérer les états de fin de trajet
Lorsqu'un conducteur arrive à destination ou arrête la navigation, la charge utile renvoie l'un des états de fin suivants. Utilisez ces états pour déclencher les étapes suivantes appropriées dans votre application.
| État | Description | Action recommandée |
|---|---|---|
ARRIVED |
Le conducteur est arrivé à destination. | Vérifiez remainingDistanceMeters. Si le conducteur s'est garé
à proximité, mais pas aux coordonnées exactes, envisagez de fournir des indications pour piétons
dans votre application. |
SUSPENDED |
Le conducteur a quitté manuellement la navigation détaillée avant d'arriver
à destination. Étant donné que Google Maps ou Waze ne renvoie pas automatiquement les conducteurs à votre application lorsqu'ils quittent une session plus tôt, le conducteur doit appuyer manuellement sur le bouton de retour. |
Pour aider les conducteurs à terminer leur trajet, comparez
execution.location à la destination. S'il reste une distance
à parcourir, fournissez un bouton ou un lien pour reprendre le trajet ou passer en mode
piéton. |
FAILED |
Une erreur technique a interrompu la connexion. Cela se produit si l'application ne parvient pas à calculer un itinéraire ou si un avertissement de sécurité s'affiche. Le conducteur peut toujours être en train de naviguer, mais vous ne recevrez pas de mises à jour. | Revenez au suivi manuel de l'état dans votre application. |
CLIENT_ERROR |
Cet état s'affiche pour l'une des raisons suivantes :
|
Revenez au suivi manuel de l'état dans votre application. |