Trip Workflow

Trip Management is a stateful, RESTful web service. It generates a trip plan for dispatch to drivers. It then continuously monitors real-time events so it can notify the back office with updated drive times and ETAs.

In order for the service to know what is happening out on the road, the Trip Management APIs are called repeatedly to:

• Gather information about a vehicle’s location from GPS pings
• Retrieve updates about a driver’s activity on the road
• Make unexpected changes in the driver’s trip plan

This page takes you through the essential steps for planning, updating and executing trips using these APIs.

Standard Flow of a Trip

Planning a Trip

The first step in any interaction with Trip Management is to create a trip using the Plan Trip API. It creates an optimized route for all of your stop locations, including rest stops. All other Trip Management APIs update or modify that trip or retrieve information about it.

• Once the trip is created, the default tripStatus is set to Planned and this will be displayed accordingly in the API response. tripStatus is monitored until the trip is completed.

Setting a Trip to In Progress

Once the driver hits the road, tripStatus changes to InProgress. This happens in one of three ways:

• GPS Pings are received from outside of the planned start location (origin) of the trip via the Update Positions API.
• status is set to Accepted via a call to the Update Trip Status API.
• The stopState for any stop is updated to Arrived or Completed/Departed via a call to the Update Stop Status API.

Arriving at a Stop

As the trip progresses, it’s important for the Trip Management service (and a transportation company’s back office) to know when a vehicle has arrived at a stop. Stop Status for arrival is updated in two ways:

• Manually by updating the stopState for the current stop to Arrived via a call to the Update Stop Status API.
• Automatically if Auto Arrive/Depart functionality is enabled and a GPS position/ping is reported from within the stop location via the Update Positions API. (Please read more below about Auto Arrive.)

Note: We highly recommend calling the Recalculate Trip API after an Arrival event to return updated trip details and a revised ETA.

Auto Arrive

Auto Arrive is enabled via an API key setting. It is disabled by default but can be enabled by contacting Trimble Maps support. Once enabled:

• If a GPS ping is received within a planned stop that has not been marked as Arrived, then the stop will be updated as Arrived.
• The bounding box for the GPS ping to trigger arrival is based on the stop’s Site, if one exists. If a Site does not exist, the box is a 0.5-mile radius geofence around the stop location.

Departing a Stop

Once the driver has completed their activity at the stop, the Trip Management service will next want to know when they depart the stop. Similar to arrival, stop status for departure is updated in one of two ways:

• Manually by updating the stopState for the current stop to Departed/Completed via a call to the Update Stop Status API.
• Automatically if Auto Arrive/Depart functionality is enabled and a GPS position/ping is reported via the Update Positions API from outside of a stop location already marked as Arrived . (Please read more below about Auto Depart.)

Note: We highly recommend calling the Recalculate Trip API after a Departure event to return updated trip details and a revised ETA.

Auto Depart

Auto depart is enabled via an API key setting. It is disabled by default and can be enabled by contacting Trimble Maps support. Once enabled:

• If a GPS ping is received outside of a planned stop that has been marked as Arrived, then the stop will be updated as Departed/Completed.
• The bounding box for the GPS ping to trigger departure is based on the stop’s Site, if one exists. If a Site does not exist, the box is a 0.5-mile radius geofence around the stop location.

Completing an Active Trip

Once all of the stops on a trip have been completed, the trip needs to be marked as Completed so that is no longer active. This happens one of three ways:

• If Auto Arrive/Depart is enabled (via API key) and a GPS ping is sent from the final stop. (All other stops must be completed.)
• The stopState for the final stop is updated to Arrived or Departed/Completed via a call to the Update Stop Status API. All other stops must also be completed.
• The trip status is marked as Completed via a call to the Update Trip Status API.

Canceling an Active Trip or Stop

Trips can also be canceled by setting the trip status to Canceled via a call to the Update Trip Status API.

The trip would also be marked as Completed if the stopState of the final stop in the trip is marked as Canceled via the Update Stop Status API.

Trip Modifications

The Trip Management service allows you to modify a trip at any point prior to completion.

Recalculating an Active Trip

Each time there are changes to the trip, it needs to be recalculated so the service returns updated trip details and revised ETAs. The service recalculates automatically in the following situations:

• Once a trip begins and the tripStatus changes to InProgress.
• After a trip has been modified with the Modify Trip API, which is called if the back office adds or removes a stop, or if the driver adds a rest stop.
• After an ETA event. If there has been some issue in the trip that has triggered a change of arrival time, a recalculation is automatically performed.

For other changes to the trip, the Recalculate Trip API needs to be called to recalculate the uncompleted portion of the trip. Common situations in which you should recalculate include:

• After an Arrival or Departure event
• After an Out of Corridor event when leaving the route
• After an Out of Corridor event when returning to the route

Recalculations are based on the most recently recorded position, which is the vehicle’s position at:

• The Actual Arrival time at a stop
• The Planned Departure time if Arrived at a stop and Planned Departure time is later than the last received GPS ping timestamp and Actual Arrival Time
• The latest GPS ping timestamp if the timestamp is later (more recent) than the Actual Arrival Time and Planned Departure Time

Modifying an Active trip

You might want to modify a trip in progress to add or remove stops, change stop details or change vehicle settings. Whatever the reason, trips can be modified using the Modify Trip API. The most important thing to remember when calling Modify Trip is the PUT request body needs to contain any elements of the current trip that are being retained. That includes:

• Completed stops marked with a stopStatus of Completed. The modify response will update the stop status as Open by default if no stopStatus is passed. If a completed stop is omitted from the Modify request, an error will be returned.
• Any Open stops that should remain in the trip need to be included or they will be removed from the response. To remove an open stop during a Modify request, simply do not include it in the stop list.
• To add a stop, include all of the stop details within the stop array. The order in which the stops are passed is the stop order that will be returned.
• After a Modify Trip request, the service automatically recalculates the trip to get the updated ETAs for your newly modified trip plan. Call Get Trip to view the updated trip.

Maintaining Accurate ETAs and Updates

The Trip Management service calculates ETAs based on current vehicle position, driver Hours of Service (HOS), and live and predictive traffic speeds. It can provide notifications to the back office when events occurred that impact planned ETAs.

Receiving Trip Notifications

There are two methods for requesting Trip Notifications:

• The Notifications Service, which allows you to register your integration to receive real-time notifications as they become available.

• The Get Trip Notifications API - This can be called using a specific TripID assigned by Trimble Maps (alkTripId) when the trip was planned. This call will return all notifications for a given trip. Notifications for this call will be retained for 4 days.

Differences Between Event and Trip Notifications

Event Notifications Service
WebSocket: wss://notifications.trimblemaps.com/register
Trips: All active trips
Use case: Live monitoring
Alerts: Only new (unread) alerts

Get Trip Notifications
Resource URL: https://tripmanagement.alk.com/api/trip/{tripId}/events
Trips: Only a specific trip
Use case: Full event history
Alerts: All alerts that have been issued

Types of Notifications

Event Notifications will be the primary indicator of a change in trip ETA. These notifications cover any event that happens along the trip that could affect arrivals or change the outcome of a planned trip. The two major notifications that affect ETAs are:

• ETA events - An ETA event is when the time of arrival at the next stop changes. (Please see ETA events for more details.)
• Out of Corridor (OoC) events - An OoC event is when a GPS ping shows a vehicle has departed from the planned route corridor by more than a preset distance threshold.

Other events include:

• Weather events - These are notifications about weather along the route for a given trip.
• Out of Route (OoR) events - This is a post trip notification that provides the number of miles the vehicle traveled outside of the planned route for a given trip ID.

ETA Events

An ETA event occurs when a driver is delayed longer than expected. It is triggered when:

• The ETA of a stop is outside of its arrival time window. That time window is set when planning the trip by setting an earliestArrivalTime and latestArrivalTime for a stop.
• If only a plannedETA for a stop is set when the trip is planned, an ETA notification is sent if the current ETA is later than the plannedETA.

The threshold for how often ETA events will be triggered is configured when the Trip Management API key is set up. An ETA alert will be sent at a default maximum frequency of once every 5 minutes IF there was an ETA change. This is dependent on how often updated GPS pings are received.

You can contact Trimble Maps Support to change this threshold.

After an ETA notification is received, the service automatically recalculates to ensure the trip has up-to-date ETAs for remaining stops.

Out of Corridor (OoC) Events

An OoC event occurs when a driver leaves the planned route path beyond a preset a mileage threshold. The threshold for triggering an OoC event is configured either:

• On a global level for all trips in the Trip Management API key. The default setting is 1 mile from the route line.
• On a trip-by-trip basis using the Trip Settings API.

There are two types of OoC notifications:

• The driver departs from the defined route corridor. A notification is triggered called an “OoC departure.”
• The driver rejoins the planned route path. A notification is triggered called an “OoC rejoin.”

Recalculating after an OoC Event

The best action after an OoC event is to do nothing until an ETA event notification is received. The ETA notification will cover the scenario where the OoC event causes a significant change to ETA.

If the OoC event does not significantly change the ETA, then there is no requirement for a recalculation. Post trip analysis will show the planned vs actual route.

If you do recalculate after an OoC notification is received, please be aware the route path will be updated and the planned route path will be lost. (These changes are often minimal and equate to the route path guiding back to the previous route path.)