Trip Telemetry

The mobile app transmits trip changes and trip snapshots to your Trip Change web service to ensure your backend systems remain synchronized with the user's active route. This telemetry allows you to track modifications users make to a trip, such as moving a location pin, deviating from the planned route, or restarting navigation. Additionally, the platform provides mechanisms to collect diagnostic information and routing feedback directly from users by enabling navigation issue reports.

Trip Changes

The Trip Change web service is a webhook-style endpoint that allows your backend to receive real-time updates whenever a user modifies a trip or the mobile app generates certain tracking events. These changes are delivered to your system as soon as the platform receives them.

Key Components

username: Identifies the user who triggered the trip change.
load_id: The identifier for the load to which the trip change applies.
type: The type of trip change that was sent.
timestamp: The date and time of the trip change.

If a stop is affected (e.g., a change-stop-location event), the location field will reflect the original stop's location before any moves occurred. Refer to our Trip Change API for further information on the different trip change types.

IMPORTANT: New trip change types will be added in the future. Your service must silently ignore any type it does not currently recognize.

TIP: Network interruptions can cause the same trip change to be delivered multiple times. Store the trip change handle to ensure your system does not create duplicate entries.

Trip Snapshots

While Trip Changes alert you to individual events, the Trip Snapshots API allows you to fetch the exact state of a route at a given moment. Most Trip Changes include a latest_trip_plan_uri and occasionally an associated_trip_plan_uri that points directly to this API.

Snapshots will contain:

A JSON representation of the load with all trip changes applied.
The complete set of individual trip changes applied to that load.
The routing properties and geometry coordinates presented to the user.
NOTE: If a user is rerouted mid-trip, the platform attempts to combine the newly generated route with the route the user has already driven, ensuring the snapshot accurately reflects the entire driven path.

Exceptions

The following trip change types are strictly telemetry/reporting and do not generate snapshot URIs, nor do they appear in App Manager's Trip Planner Studio:

update-location
issue-report
geofence-entered
geofence-exited

Reason Codes

Every snapshot highlights the reason it was created. If changes happen while the device is offline, a single snapshot may list multiple reason codes once connectivity is restored.

The following reason codes are unique to snapshots:

original: The first snapshot generated when a trip is initially viewed on the device.
changed_by_client: The back office modified the load (e.g., changed stop order, added/deleted stops).
new_guidance_route: The user triggered turn-by-turn guidance to a specific stop.
driver_reroute: The user drove off the previous route and was given a new one.
system_reroute: The system provided a better route, such as avoiding new traffic congestion.
Safety codes: Codes such as add_avoid_safety_finding indicate the driver interacted with an app safety finding.

NOTE: In addition to the reason codes above, snapshot reason codes may contain codes from the Trip Change API.

IMPORTANT: Currently, trip changes and snapshots are not generated when navigating to the first stop of a load.

You can enable navigation issue reports on a load-by-load basis by setting the allow_reporting_issue_in_navigation property in your Loads web service response. Users will occasionally encounter problems during turn-by-turn navigation, such as unreported road work, incorrect trucking restrictions, directional defects, or unexpected guidance behavior.

When enabled, a Report Issue button appears on the turn-by-turn navigation screen. When a user taps this button, the mobile app immediately collects diagnostic information and sends it to the server. To avoid distracting the user, no additional input is collected at the time of reporting; the mobile app displays only a confirmation that the report was captured.

NOTE: If the device has lost network connectivity, the issue report is delivered once connectivity is restored.

Each issue report is delivered to your Trip Changes web service and includes information about the user, the ID of the load on which they were navigating, the local time, app version, and location of the user.

TIP: You can use this data to automatically generate a post-trip task for the user requesting additional detail, such as a written description of the problem or multiple-choice options for the issue type. For full details on report contents, see the issue-report section under the type property in the Trip Changes API documentation.

Resolving Issues

How you resolve an issue depends on its cause. Issue reports are retained for 180 days after the user initiates the report.

Load or routing issues: Update your Loads web service to reflect the user’s feedback.
App behavior or road network issues: Reference the environment, username and timestamp with timezone when submitting a support ticket. This gives our support team the context needed to investigate.