Trip Workflow

Contents

Trip Management is 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 event notifications and 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 #

Trip Management Workflow
The basic steps from planning to completing a trip, and the APIs that support those steps

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:

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.

Modify Trip Workflow
The steps and related APIs for modifying a trip

Recalculating an Active Trip #

The Recalculate Trip API recalculates the uncompleted portion of the trip. It should be called each time there are changes to the trip so the service updates and returns trip details and revised ETAs. Common situations in which you should recalculate include:

  • After a trip has been Modified
  • After an Arrival or Departure event
  • After an ETA event is received
  • 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.
  • A recalculate is required after a Modify Trip request to get the updated ETAs for your newly modified trip plan.

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.

Accurate ETA Workflow
The steps and related APIs for maintaining accurate ETAs

Receiving Trip Notifications #

There are two methods for requesting Trip Notifications:

  • The Event Notifications API - This should be called at a frequent interval. (We recommended every 5 minutes). It will return only new notifications for all trips associated to the API key. Once a notification is received, it will not be sent again via this API call.

  • 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.

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.

Recalculating After an ETA Event #

After an ETA notification is received, we recommended you recalculate the trip by calling the Recalculate Trip API. This will ensure the trip has up-to-date ETAs for remaining stops.

Calling recalculate more often is only recommended if minute-by-minute ETA updates are needed. In almost all cases, calling recalculate without first receiving an ETA notification will not change the ETA.

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.)

Last updated April 24, 2021.