When you [retrieve your trip data](https://developers.google.com/maps/documentation/navigation/connect/retrieve-trip-data.md.txt), 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). Because these updates
reflect the driver's active, real-time route, they may differ from routes
pre-calculated by your backend (see [FAQ](https://developers.google.com/maps/documentation/navigation/connect/faq.md.txt#route-adherence)).

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.

```json
{
  "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
  }
}
```

> [!NOTE]
> **Note:** If you receive your data using Google Cloud Pub/Sub, the service wraps the trip updates in a standard message envelope. The data field contains the actual Navigation Connect JSON payload.

## Monitor active trip statuses

To confirm a successful start and monitor progress, evaluate the
[`state`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#Trip.FIELDS.state) field in every
payload.

| Status | Description |
|---|---|
| [`NEW`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#State.ENUM_VALUES.NEW) | The trip is created, but the driver hasn't started navigating yet. |
| [`ENROUTE`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#State.ENUM_VALUES.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`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#TripExecution.FIELDS.stop_added_in_route)
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

> [!NOTE]
> **Note:** Remaining route reporting triggers the [Navigation Connect Enterprise SKU](https://developers.google.com/maps/documentation/navigation/connect/usage-and-billing.md.txt#pricing-for-product).

If you've enabled remaining route reporting [during trip creation](https://developers.google.com/maps/documentation/navigation/connect/create-trip.md.txt#optional-configurations),
your backend receives the remaining route polyline and real-time traffic
conditions from the driver's current location to their final destination.
Drivers need Waze version 5.20.0.2 or later on
Android, 5.20.0.1 or later on iOS, or Google Maps for
Android version 26.27 or later.

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 (see [FAQ](https://developers.google.com/maps/documentation/navigation/connect/faq.md.txt#route-adherence) for details on why real-time and pre-calculated routes may differ).

Navigation Connect returns the remaining route details in the
[`execution.remainingRoute`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#TripExecution.FIELDS.remaining_route)
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](https://developers.google.com/maps/documentation/navigation/connect/retrieve-trip-data.md.txt#polyline-formats).

For all polyline formats, Navigation Connect returns traffic as a separate list of
[`SpeedReadingInterval`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#SpeedReadingInterval)
objects in the
[`execution.remainingRoute.trafficInformation`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#Route.FIELDS.traffic_information)
field. These objects map traffic categories to the polyline indexes using the
following values:

- [`startPolylinePointIndex`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#SpeedReadingInterval.FIELDS.start_polyline_point_index): The starting index of the traffic interval on the polyline.
- [`endPolylinePointIndex`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#SpeedReadingInterval.FIELDS.end_polyline_point_index): The ending index of the traffic interval.
- [`speed`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#SpeedReadingInterval.FIELDS.speed): The traffic category for this segment: `NORMAL`, `SLOW`, or `TRAFFIC_JAM`.

### Google Cloud Pub/Sub updates

When you [retrieve trip data with Pub/Sub](https://developers.google.com/maps/documentation/navigation/connect/retrieve-trip-data.md.txt#use-pubsub),
updates always return remaining route data in a unified GeoJSON
`FeatureCollection` in the
[`execution.remainingRoute`](https://developers.google.com/maps/documentation/navigation/connect/reference/pubsub/rest/Shared.Types/NavigationConnectEvent.md.txt#TripExecution.FIELDS.remaining_route)
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:

```json
{
  "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`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#TripConfig.FIELDS.pubsub_field_mask)
parameter in your [`TripConfig`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#TripConfig)
object during trip creation to exclude heavy fields. For details, see [Optional
configurations](https://developers.google.com/maps/documentation/navigation/connect/create-trip#optional-configurations).

## Handle route deviations (Waze only)

> [!NOTE]
> **Note:** Route deviation reporting triggers the [Navigation Connect Enterprise SKU](https://developers.google.com/maps/documentation/navigation/connect/usage-and-billing.md.txt#pricing-for-product).

Drivers need Waze version 5.22 or later.

If you've enabled route deviation reporting [during trip creation](https://developers.google.com/maps/documentation/navigation/connect/create-trip.md.txt#optional-configurations),
when a driver goes off-route, the API returns route deviation metadata. You can
access this data in the following ways:

- **On-demand:** Call the `GetTrip` method. The server persists the last known deviation state.
- **Real-time:** Subscribe to Google Cloud Pub/Sub. The service publishes deviation updates using the existing `updated_trip` event within 5 seconds of detection.

### Read the deviation payload

The `last_route_deviation` object provides the following metadata to help you
analyze the event.

| Field | Type | Description |
|---|---|---|
| `location` | `LatLng` | The latitude and longitude coordinates where the client device recorded the deviation. |
| `source` | `TriggerSource` | The reason for the deviation. Use this to determine if the driver took an unexpected action or followed system guidance: - `DRIVER_INITIATED_REROUTE`: The driver made an active choice (for example, taking a wrong turn or manually selecting a new path). - `SYSTEM_INITIATED_REROUTE`: The navigation app calculated a new route (for example, due to changing traffic conditions or road closures). |
| `client_timestamp` | `Timestamp` | The time the client device detected the deviation. |
| `server_timestamp` | `Timestamp` | The time the server processed the deviation update. |

## 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`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#State.ENUM_VALUES.ARRIVED) | The driver reached the destination. | Check the [`remainingDistanceMeters`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#TripExecution.FIELDS.remaining_distance_meters). If the driver parked nearby but not at the exact coordinates, consider providing walking directions in your app. |
| [`SUSPENDED`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#State.ENUM_VALUES.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. > [!NOTE] > **Note:** If the driver uses the return button to switch back to your app without exiting the active navigation session, the trip status remains [`ENROUTE`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#State.ENUM_VALUES.ENROUTE). For more information, see [Handle mid-trip app > switching](https://developers.google.com/maps/documentation/navigation/connect/mid-trip-app-switching.md.txt). | To help drivers complete their journey, compare [`execution.location`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#TripExecution.FIELDS.location) against the destination. If distance remains, provide a button or link to resume the trip or switch to walking mode. |
| [`FAILED`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#State.ENUM_VALUES.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`](https://developers.google.com/maps/documentation/navigation/connect/reference/rest/v1/projects.trips.md.txt#State.ENUM_VALUES.CLIENT_ERROR) | This status appears for one of the following reasons: - The driver revokes consent. - The driver uses an unsupported platform, such as Android Auto or Apple CarPlay. - Your app reuses a trip token across separate trips. For example, Navigation Connect rejects requests that change a trip destination or update a completed trip. - The driver is located in the United States at any point during the trip, but your app doesn't have data sharing in the United States enabled when you [verified your app during setup](https://developers.google.com/maps/documentation/navigation/connect/setup-api.md.txt#provide-app-details). | Fall back to manual status tracking in your app. |