Plan Trip

The Plan Trip API creates an optimized route for your locations and allows you to do trip planning by providing the following:

  • Stops given as addresses or coords
  • Routing Profile with vehicle dimensions, type, routing type, trip options such as hazmat, avoid tolls and elevation.
  • Driver Hours of Service with values for each of the HOS clocks, HOS rule type and custom break duration

The generated trip will have the following details:

  • Trip distance
  • Trip duration
  • Trip costs
  • Trip tolls
  • HOS remaining hours
  • Inserted HOS rest stops
  • Arrival and Departure time at every stop
  • Leg distance and duration for every stop

POST /trip

Resource URL

https://tripmanagement.alk.com/api/trip

Request Fields

Trip Identifiers

Field Description Type Required
storeTrip If false, an alkTripId for the trip will not be generated and the trip details will not be stored by Trimble for future manipulations.
boolean
No, default is True
tmsId Indicates which TMS type that the trip will use. This value can only be set in PlanTrip and is not nullable. Please pass with a value or omit the field.
  • 0 or “None”
  • 1 or “TMWSuite”
  • 2 or “ALK”
Enum
No, not nullable
tspId Telematics Solutions or MobilComm Provider ID provided by Trimble MAPS.
string
No
tmsTripId The trip ID (Load ID or Order number) in the TMS system.
string
Yes
tmsCustomerId The customer or company ID in the TMS system - client who purchased the Trip Management Solution.
string
No
tmsUserId The user ID in the TMS system.
string
No
tmsUserEmail Email address to send email notifications on exceptions and alerts. Multiple email addresses can be included separated with commas. The maximum number of characters supported is 4000.
string
No
name A display name for this trip that can be used when trip information is shared or displayed.
string
No
hosSolution Indicates whether or not to insert rest stops along the route
  • 0 = do not insert rest stops,
  • 2 = insert rest stops using Trimble MAPS
Enum
No, default is 0
plannedStartTime The planned start date and time of the trip at the planned start location. The value must be in ISO-8601 format. This time is important in order for ETA calculations to take into account the impact of historical traffic patterns along the route.
String
No, default is “now”.
plannedStartLocation The planned starting location in latitude > longitude.

The default start location of the trip is the first stop specified. If the user wants to have a dedicated start location, it can be set with this parameter. An example for a start location could be the current location of a truck when accepting a job. In that case, the truck has to drive from the current location (plannedStartLocation) to the first stop specified in the trip.

Coords object
No, default is the location of the first stop
plannedStartLocation > coords > lat The latitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits.
string
No
plannedStartLocation > coords > lon The longitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits.
string
No
region Indicates which region to be set for the trip. Must be set unless using the default region, North America (NA).
  • 1 or “AF”
  • 2 or “AS”
  • 3 or “EU”
  • 4 or “NA”
  • 5 or “OC”
  • 6 or “SA”
  • 7 or “ME”
Enum
No. Default is 4 or NA

Stop Locations

Field Description Type Required
stops The stop array specifies an array of stops for the route that will be generated. Multiple values (below) can be set for each stop.
Array <Stop>
Yes
stops > stopType Type of stop
  • Origin - The first stop on the trip. Most trips have an “origin” and a “destination” with stops in between. The Origin is also used as the “planned start location” if the plannedStartLocation parameter is not provided.
  • Work - A standard stop within a trip.
  • Waypoint - A point used to help shape the route, if needed. The driver passes through a waypoint, but doesn’t have to stop at a waypoint.
  • FuelStop - A planned fuel stop.
  • RestStopShort - The rest stop planned for a short break. (Please see HOS for more details.)
  • RestStopLong - The rest stop planned for a long break. (Please see HOS for more details.)
  • RestStopCycleReset - The rest stop planned to reset the drive time cycle. (Please see HOS for more details.)
  • Destination - The final stop in a trip.
  • RestStopFullDay - The rest stop for a day break. (Please see HOS for more details.)
  • RestStopDriverSwitch - The rest stop used to swap drivers. (Please see HOS for more details.)
  • BorderCrossing - North America only. This is triggered automatically if you cross a border, and it is added as a stop. Border crossings will have a dwell time of 1 hour automatically added.
string
No. Default is Work
stops > location Each stop array must have either coord object or address object for location.
Location object
Yes
stops > location > address An address object representing the street address, city, state, and postal code of a stop.
Address object
Yes, if coords object is not supplied.
stops > location > address > streetAddress The street address of this trip stop.
string
Yes, if coords object is not supplied.
stops > location > address > city The city of this trip stop.
string
Yes, if coords object is not supplied and if zip is not provided in the address object.
stops > location > address > state The state of this trip stop.
string
Yes, if coords object is not supplied.
stops > location > address > zip The zip > postal code of this trip stop.
string
Yes, if coords object is not supplied and if city is not provided in the address object.
stops > location > address > county The county where this trip stop is located.
string
No
stops > location > coords Contains the latitude and longitude of the stop.
Coords object
Yes, if address object is not supplied.
stops > location > coords > lat The latitude of the stop. Minimum 4 decimal digits required. Desired 6 decimal digits.
string
Yes, if address object is not supplied.
stops > location > coords > lon The longitude of the stop.Minimum 4 decimal digits required. Desired 6 decimal digits.
string
Yes, if address object is not supplied.
stops > location > label A display name for this trip stop.
string
No
stops > earliestArrivalTime The start of the arrival time window at the stop. The value must be in ISO-8601 format. During the trip, this time is monitored and a notification is provided if the calculated arrival time is earlier than the defined time.
string
No
stops > latestArrivalTime The end of the arrival time window at the stop. The value must be in ISO-8601 format. During the trip, this time is monitored and a notification is provided if the calculated arrival time is later than the defined time.
string
No
stops > plannedDuration The time planned to be at the stop location in minutes. Typically also defined as “dwell time.” Dwell times impact the ETAs.
double
No
stops > atRiskThreshold Threshold can be set in minutes and is monitored during execution. If the calculated ETA is within the defined time window but falls into the threshold, an “At Risk” notification is triggered.

For example, if set to 20 minutes, and the delivery window is from 1pm-3pm, the stop is At Risk if the ETA is anywhere between 2:40pm and 3:00pm. The stop is On Time if ETA is prior to 2:40pm, and Late if ETA is after 3:00pm.

integer
No, default is 15
stops > tooEarlyThreshold Threshold can be set in minutes and is monitored during execution. If the calculated ETA falls into the threshold before the earliestArrivalTime, a “Too Early” notification is triggered. For example, if set to 20 minutes, and the delivery window is from 1pm-3pm, the stop is “Too Early” if the ETA is anytime before 12:40pm.
integer
No, default is a high number
stops > metadata Notes that can be stored with the stop. These will not be delivered to the driver.
string
No

Vehicle, Driver and Load Details

Field Description Type Required
vehicle The vehicle object contains information about the vehicle.
Vehicle object
No
vehicle > tspVehicleId The ID for the vehicle assigned to the trip in the telematics providers system. Not actively used within Trip Management API.
string
No
vehicle > isHighValue Vehicle is carrying a high value load. For informational purposes only. Does not impact route calculation.
boolean
No, default is False
tspDriverId The fleetwide unique identifier of the driver. Not actively used within Trip Management API.
string
No
externalOrderIds An array of external Order IDs associated with the trip. Max Array Length is 30 and Max Length of each Order ID is 50 characters.
Sample: “externalOrderIds”:[“Order1”,“Order2”,“Order3”]. Not actively used within Trip Management API.
Array <string>
No

Hours of Service - Fields for All Regions

Hours of Service (HOS) legislation regulates how long a driver is allowed to drive and how often and for how long he or she needs to break. The use of HOS logic is optional and can be configured using the parameters below. If HOS is selected, the Trip Management API inserts the appropriate (legally required) break times into a trip and finds a suitable location at the time the break needs to be taken.

Each HOS rule set (NA, Canada, Europe) has its own distinct rules which differ significantly. HOS breaks can extend the duration of a trip significantly, but as they are legally required, they need to be factored into the ETA.

The various parameters (e.g. daily drive time, on-duty time, etc.) work with standard values but the controlling application can overwrite those, for example, if live data from an ELD (in Europe “Digital Tachograph") is used.

Field Description Type Required
driverHoursOfService The hours of service parameters, if using the Trimble MAPS HOS solution.
driverHoursOfService object
No.
driverHoursOfService > Enabled If false, HOS rest stops will not be inserted in route.
boolean
No. Default is True
driverHoursOfService > HoSRuleType Indicates which hours of service rule type to follow
  • 0 or “USFed607LH”
  • 1 or “USFed708LH”
  • 2 or “CanadaCycle1”
  • 3 or “CanadaCycle2”
  • 4 or “California808”
  • 5 or “Texas707”
  • 6 or “Europe”
  • 7 or “USShortHaul”
HoSRuleType is required to use hours of service calculations if hosSolution is set to 2. Otherwise it is optional.
Enum
Yes, if hosSolution=2
driverHoursOfService > AlternateHoSRuleType Indicates an alternate hours of service rule type to follow whe making cross border moves between Canada and the United States.
  • 0 or “USFed607LH”
  • 1 or “USFed708LH”
  • 2 or “CanadaCycle1”
  • 3 or “CanadaCycle2”
  • 4 or “California808”
  • 5 or “Texas707”
  • 6 or “Europe”
  • 7 or “USShortHaul”
Enum
No. Default is null
driverHoursOfService > UseCustomPlaces If true, custom locations will be used where possible for HOS rest break.
boolean
No. Default is False
driverHoursOfService > CustomBreakDurations Longer custom durations for rest stops will be used instead of mandated minimum durations by default.
object
No.
driverHoursOfService > CustomBreakDurations > ShortBreakDuration Custom duration in minutes for short rest break instead of mandated minimum 30 minutes.
double
No.
driverHoursOfService > CustomBreakDurations > EndOfDutyBreakDuration Custom duration in minutes for end of duty break instead of mandated minimum 10 hours.
double
No.
driverHoursOfService > CustomBreakDurations > CycleResetBreakDuration Custom duration in minutes for cycle reset instead of mandated minimum 34 hours (US) and 36 hours (Canada).
double
No.
driverHoursOfService > CustomBreakDurations > BorderCrossingWaitDuration Custom duration in minutes for border crossing instead of default minimum of 1 hour.
double
No.
driverHoursOfService > MaxAlternateRestStops The maximum number of alternate rest stops that will be returned in the Hours of Service report.
integer
No, default is 0.

Hours of Service - Fields for U.S. Only

Field Description Type Required
driverHoursOfService > RemainingDriveTimeUntilBreak Remaining time in seconds until short break.
double
No. Default is full HOS.
driverHoursOfService > RemainingDriveTime Remaining drive time in seconds for the day.
double
No. Default is full HOS.
driverHoursOfService > RemainingOnDutyTime Remaining on duty time in seconds for the day.
double
No. Default is full HOS.
driverHoursOfService > RemainingCycleDutyTime Remaining time in seconds until cycle limit.
double
No. Default is full HOS.
driverHoursOfService > CycleTimeGains An array of cycle time gains in seconds for the next 6 or 7 days.
Array <double>
No. Default is no cycle time gains.
driverHoursOfService > UseCycleReset If true, a cycle reset break will be inserted in route.
boolean
No. Default is false.
driverHoursOfService > TerminalDayStartTime Start of the 24-hour period for the driver for cycle time limit compliance
string
No. Default is midnight in the time zone of the trip origin

Hours of Service - Fields for Canada Only

Field Description Type Required
driverHoursOfService > RemainingCanadaOnDutyTime Remaining time in seconds for a day - applicable only for Canada HOS.
double
No. Default is full HOS.
driverHoursOfService > RemainingTimeUntilFullDayBreak Remaining time in seconds until a full day (24-hour) break is needed - applicable only for Canada Cycle Two HOS.
double
No. Default is full HOS.
driverHoursOfService > RemainingTimeUntilFullDayBreakDriver2 Remaining time in seconds until a full day (24-hour) break is needed for driver2 - applicable only for Canada Cycle Two HOS.
double
No. Default is full HOS.
driverHoursOfService > LastCycleResetDateTime Date and time of end of last cycle reset - applicable only for Canada HOS
string
No.
driverHoursOfService > Last24HourBreakDateTime Date and time of end of last 24 hour break - applicable only for Canada HOS
string
No.

Hours of Service - Fields for Europe Only

Field Description Type Required
driverHoursOfService > RemainingOnDutyTimeInDay The remaining on-duty time (in seconds) in a day until the driver must take a break. Only used for European HOS.
double
No. Default is full HOS.
driverHoursOfService > RemainingDrivingTimeInWeek The remaining driving time in seconds until the driver must take a weekly break. Only used for European HOS.
double
No. Default is full HOS.
driverHoursOfService > RemainingConsecutiveDrivingTime The remaining consecutive driving time (in seconds) in a day until the driver must take a break. Only used for European HOS.
double
No. Default is full HOS.
driverHoursOfService > RemainingFortnightlyTime The remaining fortnightly (bi-weekly) time (in seconds) until the drive must take a break. Only used for European HOS.
double
No. Default is full HOS.

Hours of Service - Fields for Team Driving (U.S. and Canada Only)

Field Description Type Required
driverHoursOfService > TeamDriving If true, team driving will be used and, whenever possible, the active driver will be switched instead of taking a rest break.
boolean
No. Default is false
driverHoursOfService > activeDriver For Team Driving, indicates which driver is active at the beginning of the trip.
integer
No.
driverHoursOfService > remainingDriveTimeUntilBreakDriver2 Remaining time in seconds until short break for Driver 2. Used only for Team Driving.
double
No. Default is full HOS.
driverHoursOfService > remainingDriveTimeDriver2 Remaining drive time in seconds for the day for Driver 2. Used only for Team Driving.
double
No. Default is full HOS.
driverHoursOfService > remainingOnDutyTimeDriver2 Remaining on duty time in seconds for the day for Driver 2. Used only for Team Driving. For Canada HOS this is the remaining time in seconds for a work shift.
double
No. Default is full HOS.
driverHoursOfService > remainingCycleDutyTimeDriver2 Remaining time in seconds until cycle limit for Driver 2. Used only for Team Driving.
double
No. Default is full HOS.
driverHoursOfService > cycleTimeGainsDriver2 An array of cycle time gains in seconds for the next 6 or 7 days for Driver 2. Used only for Team Driving.
Array <double>
No. Default is full HOS.
driverHoursOfService > lastCycleResetDateTimeDriver2 Date and time of end of last cycle reset for Driver 2. Used only for Team Driving. Applicable only for Canada HOS
string
No.
driverHoursOfService > last24HourBreakDateTimeDriver2 Date and time of end of last 24 hour break for Driver 2. Used only for Team Driving. Applicable only for Canada HOS
string
No.
driverHoursOfService > remainingCanadaOnDutyTimeDriver2 Remaining time in seconds for a day - applicable only for Canada HOS for Driver 2. Used only for Team Driving.
double
No. Default is full HOS.
driverHoursOfService > CustomBreakDurations > DriverSwitchBreakDuration Custom duration in minutes for driver switch instead of default minimum of 5 minutes.
double
No.

Vehicle Routing Profile

The Vehicle Routing Profile influences how the route for a specific type of vehicle is calculated. In all cases, our routing algorithm aims for a suitable and legally compliant route. This is determined by the type of vehicle, the vehicle dimensions and the load.

Field Description Type Required
routingProfile A routingProfile object containing parameters that impact routing.
object
No
routingProfile > routingType Indicates the routing algorithm to use. We recommend Practical for trucks, which is the default. Practical aims to find a balance between legally compliant, safe and quick. It avoids any roads legally not allowed for the vehicle/dimensions/load; avoids small roads and city centers; and keeps the driver on roads safe for the vehicle, the driver and the community.
  • 0 = Practical,
  • 1 = Shortest,
  • 2 = Fastest
Enum
No, default is Practical
routingProfile > vehicleType The vehicle type. While Trip Management is designed for large trucks, the functionality is also suitable for other vehicles. In addition to the routing type (see above), the vehicle type influences the route path. (A route for a car is different from a route for a large truck.)
  • 0 = Auto,
  • 3 = Truck,
  • 4 = Bus,
  • 11 = LightTruck,
  • 12 = MidsizeTruck
Enum
No, default is Truck
routingProfile > truckDimensions The truck style. You can either select a preset truck type (e.g. SemiTrailer48 or EU16Meter) or use the Custom type and define your required truck dimensions individually, using the parameters below. We have predefined the most common truck types with standard height, weight, width, length and number of axles.
  • 0 = NoRestriction,
  • 1 = SemiTrailer48,
  • 2 = TrailerOrTwins53,
  • 3 = DoubleTrailers28,
  • 4 = StraightTruck40,
  • 5 = EU16Meter,
  • 6 = EU18Meter,
  • 7 = EU12Meter,
  • 8 = EU54Foot,
  • 9 = EU61Foot,
  • 10 = EU40Foot,
  • 16 = Custom,
  • 17 = ConventionalSchoolBus,
  • 18 = SmallSchoolBus
Enum
No, default is NoRestriction
routingProfile > unitsOfMeasure The units of measure for truck dimensions and weight. If you select a truck type with metric values, ensure that you set the units of measure to Metric.
English (Imperial), Metric
string
No, default is English.
routingProfile > totalLength The total length of the truck. Only used when truckDimensions is set to Custom.
For straight trucks, it’s total length (up to 40'). For tractor-semitrailers, it’s the length of the semitrailer (usually 28', 33', 45', 48', 53') excluding the tractor. For doubles, it’s the combined length of the trailers (56') excluding the tractor.
decimal
No
routingProfile > totalWeight The gross vehicle registered weight of the truck. Only used when truckDimensions is set to Custom.
decimal
No
routingProfile > maxHeight The maximum height of the truck. Only used when truckDimensions is set to Custom.
decimal
No
routingProfile > maxWidth The maximum width of the truck. Only used when truckDimensions is set to Custom.
decimal
No
routingProfile > numAxles Vehicle number of axles. Only used when truckDimensions is set to Custom.
Acceptable values are 2 through 14.
integer
No, default is 5.
routingProfile > LCV Indicates whether the truck is a multi-trailer or longer combination vehicle. (North America only)
boolean
No, default is False.
routingProfile > hazmatType Indicates the hazardous material type.
  • None,
  • General,
  • Explosives,
  • Inhalants,
  • Radioactive,
  • Caustic,
  • Flammable
string
No, default is None.
routingProfile > tollDiscouraged Set to True to avoid toll roads. Default is False.
boolean
No, default is False
routingProfile > bordersOpen Set to True to allow international border crossings, False to avoid or reduce number of international border crossings. For example, if all your stops are in the “lower 48” United States, the resulting route will stay in the United States even if the most practical or shortest route would normally involve some Canadian mileage. (North America Only)
boolean
No, default is True
routingProfile > classOverrides Indicates preference for National Network and 53' (includes state designations) for routing. (North America Only)
  • None,
  • FiftyThreeFoot,
  • NationalNetwork
string
No, default is None
routingProfile > elevationLimit The elevation limit to use during routing. Avoids routes going above defined elevation. (North America Only)
integer
No
routingProfile > isFerryDiscouraged Set to True to avoid ferries during routing, False otherwise.
boolean
No, default is False.
routingProfile > useAvoidFavors Set to True if custom avoids and favors set up for the fleet with Trimble MAPS are to be used. Avoids and favors (collectively called Route Modifiers) is a separate function of the Trimble Maps platform. It allows fleets to define whether to avoid or favor specific roads within the road network. Read more about Route Modifiers.
You can select specific Route Modifiers sets to use in routing by setting the afSetIds or afSetNames parameters.
boolean
No, default is False.
routingProfile > governorSpeedLimit Maximum speed that the driver is permitted to use in the vehicle. The format is in mph or kph based on distUnits. This value is used for ETA calculations.
double
No.
routingProfile > distanceUnits Indicates which Distance Units the Trip Distance and Leg Distance will use.
  • 0 or “Miles”
  • 1 or “Kilometers”
enum
No.
routingProfile > useSites Another unique feature of the Trimble Maps platform is the ability for customers to define Sites. With Sites you can define a polygon around a place, define entry and exit gates and capture other valuable information about a location. More information can be found here.
boolean
No, default is False.
afSetIds Avoid or favor set Ids are used for routing. routingProfile > useAvoidFavors must be true in order to utilize avoid or favor sets supplied.
Array <integer>
No, either set ids or names
afSetNames Avoid or favor set names are used for routing. routingProfile > useAvoidFavors must be true in order to utilize avoid or favor sets supplied.
Array <string>
No, either set ids or names

Response Fields

Field Description Type
alkTripId The unique identifier for the trip. This value will be used in subsequent calls to the service pertaining to this trip.
integer
name A display name for this trip.
string
tmsTripId The trip ID in your planning system. This can be used to match a Trip Management trip with a trip in your database.
string
tripStatus The current status of the trip. For the initial response, the value will be Planned. As the trip gets executed/modified, the values may change to:

Dispatched - This is triggered when the a trip is created with a tspDriverId and the CoPilot connection is enabled. (The back office has dispatched the trip to the driver in CoPilot.)

ReceivedByClient - When a trip is accepted in CoPilot after being dispatched. The driver gets a pop-up that reads, “A new trip has been received” and, once accepted, the trip will have the ReceivedByClient status.

InProgress - This is triggered by the origin (first stop) being completed, the trip being accepted via the Update StopStatus API, or once the first GPS position is received for the trip.

Canceled - This is updated via the Update Trip Status API. This removes the trip from “active” status and the trip can no longer be modified.

Completed - This is updated via the Update Trip Status API or if the final stop in the trip is marked as completed.

Declined - This is updated via the Update Trip Status API.

string
actualStartDate The date and time when the trip is put InProgress.
date
tripDistance The total planned distance of the trip.
integer
tripDuration The total planned duration of the trip including drive time, dwell times and break times. This value is updated each time the trip is recalculated.
integer
tripDriveDuration The total duration of the trip which was spent driving, not including dwell and break time. This value is updated each time the trip is recalculated.
integer
tripCost The total cost value for the trip, including fuel, tolls, labor and vehicle costs. This cost is based on default values in the Trimble MAPS database.
integer
tripTolls The total tolls value for the trip.
integer
region Indicates which region was set to run the trip.
Enum
externalOrderIds The array of external Order IDs associated with the trip.
Array <string>
stops The stop array contains every customer stop in the trip plan as well as inserted fuel and rest stops.
Array <Stop>
stops > stopSequence The order in which the stops are executed. This includes inserted fuel and rest stops.
integer
stops > stopStatus Status of the stop

Open - A stop that has not yet been reached.

Arrived - The vehicle has reached the stop location.

Completed - The vehicle has left the stop location. A setting via API Key is available to automatically trigger Arrived and Completed if the vehicle enters or exits the location’s Site or a .5 mile geofence of the location. Without that setting, the status can be updated manually using the Update StopStatus API.

Canceled - The stop has been canceled.

NotViable - The stop is not viable.

string
stops > stopArrivalStatus Status of the stop
OnTime,AtRisk,Late,Early,NotViable
string
stops > currentETA The date and time predicted to arrive based on routing variables.
date
stops > actualArrivalTime The time of arrival at the stop, set when the status changes to Arrived. Trip Management also stores the original ETA for later analysis.
date
stops > actualDepartureTime The time of departure at the stop, set when the status changes to Completed.
date
stops > actualDuration The number of minutes the driver spent at this stop.
double
stops > stopType Type of stop
  • Origin,
  • Work,
  • Waypoint,
  • FuelStop,
  • RestStopShort,
  • RestStopLong,
  • RestStopCycleReset,
  • RestStopShortSplittable (EU ONLY),
  • RestStopBiWeekly (EU Only),
  • Destination,
  • RestStopFullDay,
  • RestStopDriverSwitch,
  • BorderCrossing
string
stops > amenities An array containing the Amenities available as this rest stop. (North America Only)
Array <string>
stops > truckServices Indicates whether this rest stop has Truck Services or not. (North America Only)
boolean
stops > activeDriver For Team Driving, indicates which driver is actively driving starting at this stop.
integer
stops > location Each stop array must have at least two location elements in it.
Location object
stops > location > address An address object representing the street address, city, state, and postal code of a stop.
Address object
stops > location > address > streetAddress The street address of this trip stop.
string
stops > location > address > city The city of this trip stop.
string
stops > location > address > state The state of this trip stop.
string
stops > location > address > zip The zip/postal code of this trip stop.
string
stops > location > address > county The county where this trip stop is located.
string
stops > location > coords Contains the latitude and longitude of the stop.
coords object
stops > location > coords > lat The latitude of the stop.
string
stops > location > coords > lon The longitude of the stop.
string
stops > location > label A display name for this trip stop.
string
stops > plannedETA Estimated date and time of arrival at the stop as of the initial trip plan when dispatched to the vehicle. The value is formatted in ISO-8601 format. If the trip is modified after the initial planning, then it will have to be recalculated to get a new ETA.
date
stops > plannedDepartureTime Estimated date and time of departure at the stop as of the initial trip plan when dispatched to the vehicle. If the trip is modified after the initial planning, then the ETA will have to be recalculated, which would also update the departure time. The value is formatted in ISO-8601 format.
date
stops > plannedDuration The estimated duration at stop in minutes.
double
stops > saveRestStop If true, this rest stop will be preserved when recalculating the route. This value is set when modifying a trip.
boolean
stops > legDistance Distance to the next stop in miles or kilometers, depending on the setting in routingProfile > distanceUnits. .
double
stops > legDriveDuration Duration to the reach the next stop in minutes.
double
alternateRestStops A list of alternate Hours of Service rest stops that may be used to replace the current rest stop
Array <AlternateHosLocation>
alternateRestStops > amenities An array containing the Amenities available as this rest stop.
Array <string>
alternateRestStops > truckServices Indicates whether this rest stop has Truck Services or not.
boolean
alternateRestStops > activeDriver For Team Driving, indicates which driver is actively driving starting at this stop.
integer
alternateRestStops > location The location of the alternate rest stop.
Location object
alternateRestStops > location > address An address object representing the street address, city, state, and postal code of the alternate rest stop.
Address object
alternateRestStops > location > address > streetAddress The street address of the alternate rest stop.
string
alternateRestStops > location > address > city The city of the alternate rest stop.
string
alternateRestStops > location > address > state The state of the alternate rest stop.
string
alternateRestStops > location > address > zip The zip/postal code of the alternate rest stop.
string
alternateRestStops > location > address > county The county where the alternate rest stop. is located.
string
alternateRestStops > location > coords Contains the latitude and longitude of the alternate rest stop.
coords object
alternateRestStops > location > coords > lat The latitude of the alternate rest stop.
string
alternateRestStops > location > coords > lon The longitude of the alternate rest stop.
string
alternateRestStops > location > label A display name for the alternate rest stop.
string
hoursOfServiceRemaining Remaining HOS parameters at the end of the trip, if using the Trimble MAPS HOS solution.
hoursOfServiceRemaining object
hoursOfServiceRemaining > enabled Indicates whether the trip was run with HOS enabled allowing rest stops insertion.
boolean
hoursOfServiceRemaining > remainingDriveTimeUntilBreak Remaining time in seconds until short break at the end of the trip.
double
hoursOfServiceRemaining > remainingDriveTime Remaining drive time in seconds for the day at the end of the trip.
double
hoursOfServiceRemaining > remainingOnDutyTime Remaining on duty time in seconds for the day at the end of the trip. For Canada HOS this is the remaining time in seconds for a work shift.
double
hoursOfServiceRemaining > hoSRuleType Indicates which HOS Rule was used to run the trip.
Enum
hoursOfServiceRemaining > alternateHoSRuleType Indicates an alternate hours of service rule type to follow whe making cross border moves between Canada and the United States.
Enum
hoursOfServiceRemaining > remainingCycleDutyTime Remaining time in seconds until cycle limit at the end of the trip.
double
hoursOfServiceRemaining > cycleTimeGains An array of cycle time gains in seconds for the next 6 or 7 days at the end of the trip.
Array <double>
hoursOfServiceRemaining > lastCycleResetDateTime Date and time of end of last cycle reset at the end of the trip - applicable only for Canada HOS.
string
hoursOfServiceRemaining > last24HourBreakDateTime Date and time of end of last 24 hour break at the end of the trip - applicable only for Canada HOS.
string
hoursOfServiceRemaining > remainingCanadaOnDutyTime Remaining time in seconds for a day at the end of the trip - applicable only for Canada HOS.
double
hoursOfServiceRemaining > remainingTimeUntilFullDayBreak Remaining time in seconds until a full day (24-hour) break is needed at the end of the trip - applicable only for Canada Cycle Two HOS.
double
hoursOfServiceRemaining > remainingTimeUntilFullDayBreakDriver2 Remaining time in seconds until a full day (24-hour) break is needed for driver2 at the end of the trip - applicable only for Canada Cycle Two HOS.
double
hoursOfServiceRemaining > remainingDriveTimeUntilBreakDriver2 Remaining time in seconds until short break at the end of the trip for Driver 2. Used only for Team Driving.
double
hoursOfServiceRemaining > remainingDriveTimeDriver2 Remaining drive time in seconds for the day at the end of the trip for Driver 2. Used only for Team Driving.
double
hoursOfServiceRemaining > remainingOnDutyTimeDriver2 Remaining on duty time in seconds for the day at the end of the trip for Driver 2. Used only for Team Driving. For Canada HOS this is the remaining time in seconds for a work shift.
double
hoursOfServiceRemaining > remainingCycleDutyTimeDriver2 Remaining time in seconds until cycle limit at the end of the trip for Driver 2. Used only for Team Driving.
double
hoursOfServiceRemaining > cycleTimeGainsDriver2 An array of cycle time gains in seconds for the next 6 or 7 days at the end of the trip for Driver 2. Used only for Team Driving.
Array <double>
hoursOfServiceRemaining > lastCycleResetDateTimeDriver2 Date and time of end of last cycle reset at the end of the trip for Driver 2. Used only for Team Driving. Applicable only for Canada HOS.
string
hoursOfServiceRemaining > last24HourBreakDateTimeDriver2 Date and time of end of last 24 hour break at the end of the trip for Driver 2. Used only for Team Driving. Applicable only for Canada HOS.
string
hoursOfServiceRemaining > remainingCanadaOnDutyTimeDriver2 Remaining time in seconds for a day at the end of the trip for Driver 2. Used only for Team Driving. Applicable only for Canada HOS.
double
hoursOfServiceRemaining > RemainingOnDutyTimeInDay The remaining on-duty time (in seconds) in a day until the driver must take a break. Only used for European HOS.
double
hoursOfServiceRemaining > RemainingDrivingTimeInWeek The remaining driving time in seconds until the driver must take a weekly break. Only used for European HOS.
double
hoursOfServiceRemaining > RemainingConsecutiveDrivingTime The remaining consecutive driving time (in seconds) in a day until the driver must take a break. Only used for European HOS.
double
hoursOfServiceRemaining > RemainingFortnightlyTime The remaining fortnightly (bi-weekly) time (in seconds) until the drive must take a break. Only used for European HOS.
double
driverHoursOfService The hours of service parameters, if using the Trimble MAPS HOS solution.
driverHoursOfService object
driverHoursOfService > useCycleReset If true, a cycle reset break is inserted in route.
boolean
driverHoursOfService > enabled If false, HOS rest stops are not inserted in route.
boolean
driverHoursOfService > terminalDayStartTime Start of the 24-hour period for the driver for cycle time limit compliance.
string
driverHoursOfService > remainingDriveTimeUntilBreak Remaining time in seconds until short break at the end of the trip.
double
driverHoursOfService > useCustomPlaces If true, custom locations are used where possible for HOS rest break.
boolean
driverHoursOfService > remainingDriveTime Remaining drive time in seconds for the day at the end of the trip.
double
driverHoursOfService > teamDriving If true, team driving will be used and, whenever possible, the active driver will be switched instead of taking a rest break.
boolean
driverHoursOfService > remainingOnDutyTime Remaining on duty time in seconds for the day at the end of the trip. For Canada HOS this is the remaining time in seconds for a work shift.
double
driverHoursOfService > customBreakDurations Longer custom durations for rest stops are used instead of mandated minimum durations by default.
CustomBreakDurations object
driverHoursOfService > hoSRuleType Indicates which hours of service rule type was followed.
Enum
driverHoursOfService > alternateHoSRuleType Indicates an alternate hours of service rule type followed when making cross border moves between Canada and the United States.
Enum
driverHoursOfService > remainingCycleDutyTime Remaining time in seconds until cycle limit at the end of the trip.
double
driverHoursOfService > maxAlternateRestStops The maximum number of alternate rest stops that will be returned in the Hours of Service report.
integer
driverHoursOfService > cycleTimeGains An array of cycle time gains in seconds for the next 6 or 7 days at the end of the trip.
Array <double>
driverHoursOfService > lastCycleResetDateTime Date and time of end of last cycle reset at the end of the trip - applicable only for Canada HOS.
string
driverHoursOfService > last24HourBreakDateTime Date and time of end of last 24 hour break at the end of the trip - applicable only for Canada HOS.
string
driverHoursOfService > remainingCanadaOnDutyTime Remaining time in seconds for a day at the end of the trip - applicable only for Canada HOS.
double
driverHoursOfService > remainingDriveTimeUntilBreakDriver2 Remaining time in seconds until short break at the end of the trip for Driver 2. Used only for Team Driving.
double
driverHoursOfService > remainingDriveTimeDriver2 Remaining drive time in seconds for the day at the end of the trip for Driver 2. Used only for Team Driving.
double
driverHoursOfService > remainingOnDutyTimeDriver2 Remaining on duty time in seconds for the day at the end of the trip for Driver 2. Used only for Team Driving. For Canada HOS this is the remaining time in seconds for a work shift.
double
driverHoursOfService > remainingCycleDutyTimeDriver2 Remaining time in seconds until cycle limit at the end of the trip for Driver 2. Used only for Team Driving.
double
driverHoursOfService > cycleTimeGainsDriver2 An array of cycle time gains in seconds for the next 6 or 7 days at the end of the trip for Driver 2. Used only for Team Driving.
double
driverHoursOfService > lastCycleResetDateTimeDriver2 Date and time of end of last cycle reset at the end of the trip for Driver 2. Used only for Team Driving. Applicable only for Canada HOS.
string
driverHoursOfService > last24HourBreakDateTimeDriver2 Date and time of end of last 24 hour break at the end of the trip for Driver 2. Used only for Team Driving. Applicable only for Canada HOS.
string
driverHoursOfService > remainingCanadaOnDutyTimeDriver2 Remaining time in seconds for a day at the end of the trip for Driver 2. Used only for Team Driving. Applicable only for Canada HOS.
double
driverHoursOfService > RemainingOnDutyTimeInDay The remaining on-duty time (in seconds) in a day until the driver must take a break. Only used for European HOS.
double
driverHoursOfService > RemainingDrivingTimeInWeek The remaining driving time in seconds until the driver must take a weekly break. Only used for European HOS.
double
driverHoursOfService > RemainingConsecutiveDrivingTime The remaining consecutive driving time (in seconds) in a day until the driver must take a break. Only used for European HOS.
double
driverHoursOfService > RemainingFortnightlyTime The remaining fortnightly (bi-weekly) time (in seconds) until the drive must take a break. Only used for European HOS.
double
afSetIds Avoid or favor set Ids are used for routing.
Array <string>
afSetNames Avoid or favor set names are used for routing.
Array <string>

Sample Request

{
  "name": "Boston to San Diego",
  "tmsTripId": "ALK1234",
  "plannedStartTime": "2017-09-21T14:11:52.522Z",
  "plannedStartLocation": {
    "Coords": {
      "Lat": "42.346619",
      "Lon": "-71.096961"
    }
  },
  "externalOrderIds":["123","abc","123+abc"],
  "stops": [
    {
      "Location": {
        "Address": {
          "StreetAddress": "4 Yawkey Way",
          "City": "Boston",
          "State": "MA",
          "Zip": "02215",
          "County": "Suffolk"
        },
        "Label": "Fenway Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "stopType": "Origin"
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "200 Union Ave",
          "City": "Memphis",
          "State": "TN",
          "Zip": "38103"
        },
        "Label": "AutoZone Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "atRiskThreshold": 30,
      "stopType": "Work"
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "1000 Ballpark Way",
          "City": "Arlington",
          "State": "TX",
          "Zip": "76011"
        },
        "Label": "Globe Life Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "atRiskThreshold": 30,
      "stopType": "Work"
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "100 Park Blvd",
          "City": "San Diego",
          "State": "CA",
          "Zip": "92101"
        },
        "Label": "Petco Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "atRiskThreshold": 30,
      "stopType": "Destination"
    }
  ],
  "routingProfile": {
    "name": "example_profile",
    "LCV": false,
    "bordersOpen": true,
    "classOverrides": "NationalNetwork",
    "elevationLimit": null,
    "hazmatType": "None",
    "isFerryDiscouraged": false,
    "maxHeight": 162,
    "maxWidth": 96,
    "numAxles": 2,
    "routingType": 0,
    "tollDiscouraged": false,
    "totalLength": 240,
    "totalWeight": 9000,
    "truckDimensions": 16,
    "unitsOfMeasure": 0,
    "vehicleType": 3
  },
  "tspDriverId": "fred",
  "vehicle": {
    "tspVehicleId": "111111",
    "fuelNetworkId": "P",
    "fuelPlanId": "545345",
    "fuelTankCapacity": 300,
    "fuelTankLevel": 250,
    "milesPerGallon": 5.5,
    "minFuelLevel": 50,
    "minEndingFuelLevel": 100
  },
  "tspId": "ALK",
  "tmsUserId": "joe_user",
  "tmsUserEmail": "yourname@yourcompany.com",
  "tmsCustomerId": "ALK",
  "tmsId": 1,
  "hosSolution": "ALK",
  "fuelSolution": "None",
  "driverHoursOfService": {
    "hosRuleType": "USFed607LH",
    "remainingDriveTime": 39600,
    "remainingOnDutyTime": 50400,
    "remainingDriveTimeUntilBreak": 28800,
    "remainingCycleDutyTime": 216000,
    "cycleTimeGains": [
      36000,
      21600,
      18000,
      46800,
      43740,
      33840
    ],
    "remainingDriveTimeDriver2": 39600,
    "remainingOnDutyTimeDriver2": 50400,
    "remainingDriveTimeUntilBreakDriver2": 28800,
    "remainingCycleDutyTimeDriver2": 216000,
    "cycleTimeGainsDriver2": [
      36000,
      21600,
      18000,
      46800,
      43740,
      33840
    ],
    "terminalDayStartTime": "12:00:00-4:00",
    "useCycleReset": false,
    "useCustomPlaces": true,
    "teamDriving": true,
    "activeDriver": 1,
    "customBreakDurations": {
      "shortBreakDuration": 3600,
      "endOfDutyBreakDuration": 43200,
      "cycleResetBreakDuration": 144000,
      "driverSwitchBreakDuration": 300,
      "borderCrossingWaitDuration": 7200
    },
    "maxAlternateRestStops": 0
  }
}

Sample Response

{
  "tripStatus": "Planned",
  "modifiedOn": "2019-01-22T18:08:46+00:00",
  "tripDistance": 3123.933,
  "tripDriveDuration": 3282,
  "tripDuration": 3282,
  "hoursOfServiceRemaining": null,
  "url": null,
  "tripCost": 6302.57,
  "tripTolls": 0,
  "tmsTripId": "ALK1234",
  "name": "Boston to San Diego",
  "stops": [
    {
      "plannedETA": "2017-09-21T10:20:53-04:00",
      "currentETA": "2017-09-21T10:20:53-04:00",
      "earliestArrivalTime": "2017-09-21T10:11:52-04:00",
      "latestArrivalTime": "2017-09-21T11:11:52-04:00",
      "plannedDuration": 0,
      "actualDuration": 0,
      "plannedDepartureTime": "2017-09-21T10:20:53-04:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "OnTime",
      "atRiskThreshold": 15,
      "tooEarlyThreshold": null,
      "legDistance": 2.247,
      "legDriveDuration": 9,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "location": {
        "address": {
          "streetAddress": "4 Hawley Place",
          "city": "Boston",
          "state": "MA",
          "zip": "02110",
          "county": "Suffolk",
          "country": null,
          "stateName": null,
          "stateAbbreviation": null,
          "countryAbbreviation": null
        },
        "coords": {
          "lat": "42.356016",
          "lon": "-71.058228"
        },
        "label": "Fenway Park"
      },
      "stopSequence": 0,
      "stopType": "Origin"
    },
    {
      "plannedETA": "2017-09-22T08:44:46-05:00",
      "currentETA": "2017-09-22T08:44:46-05:00",
      "earliestArrivalTime": "2017-09-21T09:11:52-05:00",
      "latestArrivalTime": "2017-09-21T10:11:52-05:00",
      "plannedDuration": 0,
      "actualDuration": 0,
      "plannedDepartureTime": "2017-09-22T08:44:46-05:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "Late",
      "atRiskThreshold": 30,
      "tooEarlyThreshold": null,
      "legDistance": 1310.714,
      "legDriveDuration": 1403,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "location": {
        "address": {
          "streetAddress": "200 Union Avenue",
          "city": "Memphis",
          "state": "TN",
          "zip": "38103",
          "county": "Shelby",
          "country": null,
          "stateName": null,
          "stateAbbreviation": null,
          "countryAbbreviation": null
        },
        "coords": {
          "lat": "35.142195",
          "lon": "-90.049621"
        },
        "label": "AutoZone Park"
      },
      "stopSequence": 1,
      "stopType": "Work"
    },
    {
      "plannedETA": "2017-09-22T17:03:13-05:00",
      "currentETA": "2017-09-22T17:03:13-05:00",
      "earliestArrivalTime": "2017-09-21T09:11:52-05:00",
      "latestArrivalTime": "2017-09-21T10:11:52-05:00",
      "plannedDuration": 0,
      "actualDuration": 0,
      "plannedDepartureTime": "2017-09-22T17:03:13-05:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "Late",
      "atRiskThreshold": 30,
      "tooEarlyThreshold": null,
      "legDistance": 470,
      "legDriveDuration": 498,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "location": {
        "address": {
          "streetAddress": "1000 Ballpark Way",
          "city": "Arlington",
          "state": "TX",
          "zip": "76011",
          "county": "Tarrant",
          "country": null,
          "stateName": null,
          "stateAbbreviation": null,
          "countryAbbreviation": null
        },
        "coords": {
          "lat": "32.750284",
          "lon": "-97.08119"
        },
        "label": "Globe Life Park"
      },
      "stopSequence": 2,
      "stopType": "Work"
    },
    {
      "plannedETA": "2017-09-23T13:52:38-07:00",
      "currentETA": "2017-09-23T13:52:38-07:00",
      "earliestArrivalTime": "2017-09-21T07:11:52-07:00",
      "latestArrivalTime": "2017-09-21T08:11:52-07:00",
      "plannedDuration": 0,
      "actualDuration": 0,
      "plannedDepartureTime": "2017-09-23T13:52:38-07:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "Late",
      "atRiskThreshold": 30,
      "tooEarlyThreshold": null,
      "legDistance": 1340.972,
      "legDriveDuration": 1369,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "location": {
        "address": {
          "streetAddress": "100 Park Boulevard",
          "city": "San Diego",
          "state": "CA",
          "zip": "92101",
          "county": "San Diego",
          "country": null,
          "stateName": null,
          "stateAbbreviation": null,
          "countryAbbreviation": null
        },
        "coords": {
          "lat": "32.708606",
          "lon": "-117.155498"
        },
        "label": "Petco Park"
      },
      "stopSequence": 3,
      "stopType": "Destination"
    }
  ],
  "tspDriverId": "fred",
  "vehicle": {
    "tspVehicleId": "111111",
    "fuelTankCapacity": 300,
    "fuelTankLevel": 250,
    "milesPerGallon": 5.5,
    "minFuelLevel": 50,
    "minEndingFuelLevel": 100,
    "minFuelPurchase": null,
    "fuelNetworkId": "P",
    "fuelPlanId": "545345",
    "isHighValue": false
  },
  "plannedStartTime": "2017-09-21T10:11:52-04:00",
  "plannedStartLocation": {
    "address": {
      "streetAddress": "22 Lansdowne Street",
      "city": "Boston",
      "state": "MA",
      "zip": "02215",
      "county": "Suffolk",
      "country": "United States",
      "stateName": null,
      "stateAbbreviation": null,
      "countryAbbreviation": null
    },
    "coords": {
      "lat": "42.346619",
      "lon": "-71.096961"
    },
    "label": null
  },
  "allowDriverToDeclineTrip": true,
  "oocThreshold": 1,
  "hosSolution": "ALK",
  "sendOptions": null,
  "driverHoursOfService": {
    "useCycleReset": false,
    "enabled": false,
    "terminalDayStartTime": "12:00:00-4:00",
    "remainingDriveTimeUntilBreak": 28800,
    "useCustomPlaces": true,
    "remainingDriveTime": 39600,
    "teamDriving": true,
    "remainingOnDutyTime": 50400,
    "customBreakDurations": {
      "shortBreakDuration": 3600,
      "endOfDutyBreakDuration": 43200,
      "cycleResetBreakDuration": 144000,
      "driverSwitchBreakDuration": 300,
      "borderCrossingWaitDuration": 7200
    },
    "hoSRuleType": "USFed607LH",
    "alternateHoSRuleType": null,
    "remainingCycleDutyTime": 216000,
    "maxAlternateRestStops": 0,
    "cycleTimeGains": [
      36000,
      21600,
      18000,
      46800,
      43740,
      33840
    ],
    "skipRestStopInsertion": null,
    "lastCycleResetDateTime": null,
    "activeDriver": 1,
    "last24HourBreakDateTime": null,
    "remainingCanadaOnDutyTime": null,
    "remainingDriveTimeUntilBreakDriver2": 28800,
    "remainingDriveTimeDriver2": 39600,
    "remainingOnDutyTimeDriver2": 50400,
    "remainingCycleDutyTimeDriver2": 216000,
    "cycleTimeGainsDriver2": [
      36000,
      21600,
      18000,
      46800,
      43740,
      33840
    ],
    "lastCycleResetDateTimeDriver2": null,
    "last24HourBreakDateTimeDriver2": null,
    "remainingCanadaOnDutyTimeDriver2": null
  },
  "afSetIds": null,
  "afSetNames": null,
  "region": "NA",
    "externalOrderIds": [
        "123",
        "abc",
        "123+abc"
    ],
  "alkTripId": 136
}

Error Conditions

Field Description Type Values
ErrorType The type of error that occurred.
string
ArgumentException - a required field was not supplied or an invalid value was passed. Correct the error and try again.
FuelStopException - there was a problem getting fuel stops for your route.
RestStopException - there was a problem getting rest stops for your route.
Description An error message describing what occurred.
string
This message will describe how to fix the error (in terms of validation or input error) or what went wrong. In the case of timeouts on rest stop and fuel exceptions, the best course of action may be to try again later.
ErrorCode A numerical error code (if applicable).
integer

ArgumentException example

{
  "ErrorType": "ArgumentException",
  "Description": "tmsCustomerId must be supplied.",
  "ErrorCode": null
}

FuelStopException example

{
  "ErrorType": "FuelStopException",
  "Description": "ExpertFuel Error 713:  Starting fuel level is too low.",
  "ErrorCode": null
}