When you retrieve your trip data, your backend receives JSON payloads detailing the driver's trip progress. Parse these payloads to monitor the trip, update your dispatch systems, and interpret current trip statuses to determine the next step for the driver as they progress or when a trip concludes.
Read the data payload
Google Maps or Waze sends the trip data payloads to the Navigation Connect servers when the driver starts navigating, periodically along the route (every 60 seconds by default), and when the driver arrives at the destination. Each JSON message contains relevant trip data, including the driver's road-snapped coordinates, distance traveled, and estimated time of arrival (ETA).
The following code sample shows a trip data payload for when a driver starts navigation for a trip from King's Cross to 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
}
}
Monitor active trip statuses
To confirm a successful start and monitor progress, evaluate the status field in every payload.
| Status | Description |
|---|---|
NEW |
The trip is created, but the driver hasn't started navigating yet. |
ENROUTE |
The driver is actively navigating to the destination. Use this status to confirm that the trip authenticated and started successfully. |
Handle added stops
Drivers can add stops to their route during navigation. If they do,
Navigation Connect sets the execution.stopAddedInRoute field to true in the
JSON data payload. The Navigation Connect API
continues to track the driver toward the original destination. Metrics like
estimated time of arrival (ETA), distance, and duration increase
to include the added stops.
The behavior for adding stops depends on the navigation app and matches its standard functionality:
- Google Maps: Drivers can add multiple stops to their route.
- Waze: Drivers can add only one stop. If a driver tries to add another stop, Waze prompts them to start a new navigation session instead of adding the stop to the current route.
You don't need to adjust your backend inputs to support this feature.
Troubleshoot authentication and start issues
If you don't receive an ENROUTE status, an authentication error likely
occurred. Common causes include misspelled API parameters or an expired trip
token. Check the token expiration time in your initial CreateTrip response.
If the status doesn't change from NEW to ENROUTE, the driver's device might
be preventing authentication. Navigation Connect doesn't send error messages
for these cases. Verify the following:
- The driver has Waze version 5.15.5 or higher, or Google Maps version 26.14 or higher installed.
- The driver is not using Android Auto or Apple CarPlay.
- The driver has an active internet connection.
Handle remaining route data (Waze only)
If you've enabled remaining route reporting during trip creation, your backend receives the active route polyline and real-time traffic conditions from the driver's current location to their final destination.
You can ingest and process this data to power several features in your applications, including the following examples:
- Power live tracking maps: Render the remaining route polyline on a customer-facing web or mobile map to provide visibility into the driver's journey.
- Enhance ETA accuracy: Combine the road-snapped polyline and traffic interval speeds to improve internal logistics or delivery arrival predictions.
- Analyze routing compliance: Compare the remaining route geometry against expected dispatch routes to assess driver adherence.
Navigation Connect returns the remaining route details in the
execution.remainingRoute field, whether you send a GetTrip request or
receive event-driven updates
using Google Cloud Pub/Sub. However, how the payload formats and structures this
data depends on the retrieval method you use.
GetTrip method
When you call the GetTrip method, the response format for the polyline depends
on the routePolylineFormat parameter you specified in your request. For more
information, see Customize polyline formats.
For all polyline formats, Navigation Connect returns traffic as a separate list of
SpeedReadingInterval objects in the
execution.remainingRoute.trafficInformation field. These
objects map traffic categories to the polyline indexes using the following
values:
startPolylinePointIndex: The starting index of the traffic interval on the polyline.endPolylinePointIndex: The ending index of the traffic interval.speed: The traffic category for this segment:NORMAL,SLOW, orTRAFFIC_JAM.
Google Cloud Pub/Sub updates
When you retrieve trip data with Pub/Sub,
updates always return remaining route data in a unified GeoJSON
FeatureCollection in the execution.remainingRoute field.
This format combines the polyline geometry with traffic speeds directly, removing the need to map indexes manually.
See an example Pub/Sub payload
The following code sample shows the GeoJSON structure returned in the execution.remainingRoute field within the updatedTrip object of a Pub/Sub message:
{ "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" } } ] }
Optimize payload size
Because coordinate arrays are large, including remaining route data in your Pub/Sub messages can significantly increase payload size (up to 13–14 KB per message). If you receive high-frequency updates, this volume can increase backend processing load and usage costs.
To optimize your stream, use the pubsubFieldMask parameter in your
TripConfig object during trip creation to exclude heavy fields. For
details, see Optional configurations.
Handle trip end states
When a driver reaches the destination or stops navigating, the payload returns one of the following end states. Use these statuses to trigger the appropriate next steps in your app.
| Status | Description | Recommended action |
|---|---|---|
ARRIVED |
The driver reached the destination. | Check the remainingDistanceMeters. If the driver parked
nearby but not at the exact coordinates, consider providing walking
directions in your app. |
SUSPENDED |
The driver manually exited the turn-by-turn navigation before arriving
at the destination. Because Google Maps or Waze doesn't automatically return drivers to your app when they exit a session early, the driver must manually tap the return button. |
To help drivers complete their journey, compare
execution.location against the destination. If distance
remains, provide a button or link to resume the trip or switch to
walking mode. |
FAILED |
A technical error interrupted the connection. This occurs if the app cannot calculate a route or a safety warning appears. The driver might still be navigating, but you won't receive updates. | Fall back to manual status tracking in your app. |
CLIENT_ERROR |
This status appears for one of the following reasons:
|
Fall back to manual status tracking in your app. |