Gérer les données de voyage

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 chauffeur. Analysez ces charges utiles pour surveiller le trajet, mettre à jour vos systèmes de répartition et interpréter les états actuels des trajets afin de déterminer la prochaine étape pour le chauffeur 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 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. Étant donné que ces mises à jour reflètent l'itinéraire actif du conducteur en temps réel, 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 chauffeur 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 le démarrage et suivre la progression, évaluez le champ state dans chaque charge utile.

État Description
NEW Le trajet est créé, mais le chauffeur n'a pas encore commencé la navigation.
ENROUTE Le chauffeur est en train de naviguer vers la destination. Utilisez cet état pour confirmer que le trajet a été authentifié et a commencé correctement.

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 des 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 essaie 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 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 voyage 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 chauffeur 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 chauffeur dispose d'une connexion Internet active.

Gérer les données d'itinéraire restantes (Waze uniquement)

Si vous avez activé le signalement de 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, de la position actuelle du conducteur à 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 du trajet restant sur une carte Web ou mobile destinée aux clients pour leur permettre de suivre le trajet du chauffeur.
  • Améliorer la précision de l'heure d'arrivée prévue : combinez la polyligne ancrée à la route et les vitesses d'intervalle du trafic pour améliorer les prévisions internes de logistique ou d'arrivée des livraisons.
  • Analysez la conformité des itinéraires : 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 les conducteurs (consultez les questions fréquentes pour comprendre pourquoi les itinéraires en temps réel et précalculés peuvent différer).

Navigation Connect renvoie les détails restants de l'itinéraire 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 les formats et les structures de charge utile présentent 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 polylignes, 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 :

Nouveautés 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 de trajet 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 du trafic, ce qui évite de 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 de route 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 pour exclure les champs lourds. Pour en savoir plus, consultez Configurations facultatives.

Gérer les écarts d'itinéraire (Waze uniquement)

Si vous avez activé le signalement des écarts de route lors de la création du trajet, l'API renvoie des métadonnées sur les écarts de route lorsqu'un chauffeur 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 de déviation 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_trip existant 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 Motif de l'écart. Utilisez cette option pour déterminer si le conducteur a effectué une action inattendue ou a suivi les conseils du système :
  • DRIVER_INITIATED_REROUTE : le conducteur a fait un choix actif (par exemple, en prenant une mauvaise direction ou en sélectionnant manuellement un nouvel itinéraire).
  • SYSTEM_INITIATED_REROUTE : l'application de navigation a calculé un nouvel itinéraire (par exemple, en raison de l'évolution des conditions de circulation ou de routes fermées).
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 prochaines étapes appropriées dans votre application.

État Description Action recommandée
ARRIVED Le chauffeur est arrivé à destination. Consultez l'remainingDistanceMeters. Si le chauffeur s'est garé à proximité, mais pas aux coordonnées exactes, envisagez de fournir des indications à pied 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 redirigent pas automatiquement les conducteurs vers votre application lorsqu'ils quittent une session plus tôt, ils doivent 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 marche.
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. Il est possible que le conducteur soit toujours en train de naviguer, mais vous ne recevrez pas d'informations. Revenez au suivi manuel de l'état dans votre application.
CLIENT_ERROR Cet état s'affiche pour l'une des raisons suivantes :
  • Le conducteur révoque son consentement.
  • Le conducteur utilise une plate-forme non compatible, comme Android Auto ou Apple CarPlay.
  • Votre application réutilise un jeton de trajet pour plusieurs trajets distincts. Par exemple, Navigation Connect refuse les requêtes qui modifient une destination de trajet ou mettent à jour un trajet terminé.
  • Le chauffeur se trouve aux États-Unis à un moment donné du trajet, mais le partage de données n'est pas activé dans votre application aux États-Unis lorsque vous avez validé votre application lors de la configuration.
 Revenez au suivi manuel de l'état dans votre application.