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 l'état actuel du trajet afin de déterminer la prochaine étape pour le conducteur au fur et à mesure de sa progression ou à la fin d'un trajet.
Lire la charge utile des données
Google Maps ou Waze envoie les charges utiles des données de trajet aux serveurs Navigation Connect lorsque le conducteur commence à naviguer, régulièrement le long de l'itinéraire (toutes les 60 secondes par défaut) et lorsque le conducteur 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. Comme ces mises à jour reflètent l'itinéraire actif et en temps réel du conducteur, elles peuvent différer des itinéraires précalculés par votre backend (voir les questions fréquentes).
L'exemple de code suivant montre une charge utile de données de trajet lorsqu'un conducteur démarre 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 l'état des trajets actifs
Pour confirmer que le démarrage a réussi et surveiller la progression, évaluez le champ state dans chaque charge utile.
| État | Description |
|---|---|
NEW |
Le trajet est créé, mais le conducteur n'a pas encore commencé à naviguer. |
ENROUTE |
Le conducteur se dirige activement vers la destination. Utilisez cet état pour confirmer que le trajet a bien été authentifié et qu'il a démarré. |
Gérer les arrêts ajoutés
Les conducteurs peuvent ajouter des arrêts à leur itinéraire pendant la navigation. Si c'est le 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 à ses fonctionnalités standards :
- 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 vos entrées de backend pour prendre en charge cette fonctionnalité.
Résoudre les problèmes d'authentification et de démarrage
Si vous ne recevez pas d'état ENROUTE, une erreur d'authentification s'est probablement produite. Les causes les plus courantes sont des paramètres d'API mal orthographiés ou un jeton de trajet expiré. Vérifiez le délai d'expiration du jeton dans votre réponse CreateTrip initiale.
Si l'état ne passe pas de NEW à ENROUTE, il est possible que l'appareil du conducteur empêche l'authentification. Navigation Connect n'envoie pas de messages d'erreur dans ces cas. Effectuez les vérifications suivantes :
- Le conducteur a installé la version 5.15.5 ou ultérieure de Waze, ou la version 26.14 ou ultérieure de Google Maps.
- 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
Si vous avez activé le reporting sur l'itinéraire restant lors de la création du trajet, votre backend reçoit la polyligne de l'itinéraire restant et les conditions de circulation en temps réel entre la position actuelle du conducteur et sa destination finale. Les conducteurs doivent disposer de la version 5.20.0.2 ou ultérieure de Waze sur Android, de la version 5.20.0.1 ou ultérieure sur iOS, ou de la version 26.27 ou ultérieure de Google Maps pour Android.
Vous pouvez ingérer et traiter ces données pour alimenter plusieurs fonctionnalités de vos applications, y compris les exemples suivants :
- Alimenter des cartes de suivi en direct : affichez la polyligne de l'itinéraire restant sur une carte Web ou mobile destinée aux clients pour leur donner de la visibilité sur le trajet du conducteur.
- Améliorez la précision de l'heure d'arrivée prévue : combinez la polyligne alignée sur la route et les vitesses des intervalles 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 d'envoi attendus pour évaluer l'adhérence du conducteur (consultez les questions fréquentes pour savoir pourquoi les itinéraires en temps réel et précalculés peuvent différer).
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 formate 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 polylignes.
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 mappent les catégories de trafic aux index de polylignes à 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 de 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 FeatureCollection GeoJSON unifié dans le champ execution.remainingRoute.
Ce format combine directement la géométrie de la polyligne avec les vitesses de circulation, ce qui évite d'avoir à mapper les index manuellement.
Voir 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 écarts d'itinéraire (Waze uniquement)
Les conducteurs doivent disposer de la version 5.22 ou ultérieure de Waze.
Si vous avez activé les rapports sur les écarts d'itinéraire lors de la création du trajet, l'API renvoie des métadonnées sur les écarts d'itinéraire lorsqu'un conducteur s'écarte de l'itinéraire. Vous pouvez accéder à ces données de différentes manières :
- À la demande : appelez la méthode
GetTrip. Le serveur conserve le dernier état d'écart connu. - En temps réel : abonnez-vous à Google Cloud Pub/Sub. Le service publie les mises à jour des écarts à l'aide de l'événement
updated_tripexistant dans les cinq secondes suivant la détection.
Lire la charge utile de l'écart
L'objet last_route_deviation fournit les métadonnées suivantes pour vous aider à analyser l'événement.
| Champ | Type | Description |
|---|---|---|
location |
LatLng |
Coordonnées de latitude et de longitude où l'appareil client a enregistré l'écart. |
source |
TriggerSource |
Raison de l'écart. Utilisez cette option pour déterminer si le conducteur a effectué une action inattendue ou s'il a suivi les instructions du système :
|
client_timestamp |
Timestamp |
Heure à laquelle l'appareil client a détecté l'écart. |
server_timestamp |
Timestamp |
Heure à laquelle le serveur a traité la mise à jour de l'écart. |
Gérer les états de fin de trajet
Lorsqu'un conducteur atteint la 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. | Consultez l'remainingDistanceMeters. Si le conducteur s'est garé à proximité, mais pas aux coordonnées exactes, envisagez de fournir un itinéraire à pied dans votre application. |
SUSPENDED |
Le conducteur a quitté manuellement la navigation détaillée avant d'arriver à destination. Comme Google Maps ou Waze ne renvoient pas automatiquement les conducteurs vers votre application lorsqu'ils quittent une session prématurément, 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 de la 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 peut pas calculer d'itinéraire ou si un avertissement de sécurité s'affiche. Le conducteur peut toujours être en train de naviguer, mais vous ne recevrez plus de notifications. | Utilisez le suivi manuel de l'état dans votre application. |
CLIENT_ERROR |
Cet état s'affiche pour l'une des raisons suivantes :
|
Utilisez le suivi manuel de l'état dans votre application. |