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

Request Fields

FieldDescriptionTypeRequired
storeTripIf false, alkTripId for the trip will not be generated and the trip details will not be stored by Trimble for future manipulations.booleanNo, default is True
tmsIdIndicates which TMS type that the trip will use.
0 or “None”
1 or “TMWSuite”
2 or “ALK”
EnumNo
tspIdTelematics Solutions or MobilComm Provider ID provided by ALK.stringNo
tmsTripIdThe trip ID (Load ID or Order number) in the TMS system.stringYes
tmsCustomerIdThe customer or company ID in the TMS system - client who purchased the Trip Management Solution.stringNo
tmsUserIdThe user ID in the TMS system.stringNo
tmsUserEmailEmail 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.stringNo
nameA display name for this trip.stringNo
fuelSolutionIndicates whether or not to insert fuel stops along the route
0 = do not insert fuel stops, 1 = insert fuel stops using ExpertFuel (if licensed)
integerNo, default is 0
hosSolutionIndicates whether or not to insert rest stops along the route
0 = do not insert rest stops, 1 = insert rest stops using ETAPTA (if licensed), 2 = insert rest stops using ALK
integerNo, default is 0
plannedStartTimeThe planned start date and time of the trip. The value must be in ISO-8601 format.dateNo, default is “now”.
plannedStartLocationThe planned starting location in latitude > longitude.Coords objectNo, default is the location of the first stop
plannedStartLocation > coords > latThe latitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits.stringNo
plannedStartLocation > coords > lonThe longitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits.stringNo
regionIndicates which region to be set for the trip
1 or “AF”
2 or “AS”
3 or “EU”
4 or “NA”
5 or “OC”
6 or “SA”
7 or “ME”
EnumNo. Default is 4 or “NA”
stopThe stop array specifies an array of stops for route calculation plan.Array <Stop>Yes
stop > stopSequenceThe order in which the stops are to be executed.integerNo
stop > stopTypeType of stop
Origin, Work, Waypoint, FuelStop, RestStopShort, RestStopLong, RestStopCycleReset, Destination, RestStopFullDay, RestStopDriverSwitch, BorderCrossing
stringNo. Default is Work
stop > locationEach stop array must have either coord object or address object for location.Location objectYes
stop > location > addressAn address object representing the street address, city, state, and postal code of a stop.Address objectYes, if coords object is not supplied.
stop > location > address > streetAddressThe street address of this trip stop.stringYes, if coords object is not supplied.
stop > location > address > cityThe city of this trip stop.stringYes, if coords object is not supplied.
stop > location > address > stateThe state of this trip stop.stringYes, if coords object is not supplied.
stop > location > address > zipThe zip > postal code of this trip stop.stringYes, if coords object is not supplied.
stop > location > address > countyThe county where this trip stop is located.stringNo
stop > location > coordsContains the latitude and longitude of the stop.Coords objectYes, if address object is not supplied.
stop > location > coords > latThe latitude of the stop. Minimum 4 decimal digits required. Desired 6 decimal digits.stringYes, if address object is not supplied.
stop > location > coords > lonThe longitude of the stop.Minimum 4 decimal digits required. Desired 6 decimal digits.stringYes, if address object is not supplied.
stop > location > labelA display name for this trip stop.stringNo
stop > earliestArrivalTimeThe date and time of start of the appointment window. The value must be in ISO-8601 format.dateNo
stop > latestArrivalTimeThe date and time of end of the appointment window. The value must be in ISO-8601 format.dateNo
stop > plannedDurationThe estimated duration at stop in minutes.integerNo
stop > atRiskThresholdNumber of minutes prior to the end of the delivery window that, if the driver’s ETA lands within this period, the stop will be flagged as “At Risk”. 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.integerNo, default is 15
stop > tooEarlyThresholdNumber of minutes prior to the start of the delivery window that, if the driver’s ETA lands before this period, the stop will be flagged as “Too Early”. 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. The stop is Early if ETA is prior to 1:00pm, anywhere between 12:40pm and 1:00pm.integerNo, default is a high number
stop > metadataNotes about the stop. These will not be delivered to the driver.stringNo
vehicleThe vehicle object contains information about the vehicle as well as fuel information.Vehicle objectYes
vehicle > tspVehicleIdThe ID for the vehicle assigned to the trip in the telematics providers system.stringYes
vehicle > fuelNetworkIdWhen multiple fuel networks are set up for the fleet, specifies the fuel network to use.string (limit to 1 character)No
vehicle > fuelPlanIdNumeric fuel plan ID supplied by the fuel optimization solution provider.stringYes, if fuelSolution set to ExpertFuel.
vehicle > fuelTankCapacityThe vehicle fuel capacity in gallons.integerYes, if fuelSolution set to ExpertFuel.
vehicle > fuelTankLevelThe estimated fuel level in gallons.integerYes, if fuelSolution set to ExpertFuel.
vehicle > milesPerGallonThe vehicle’s average fuel consumption rate in miles per gallon.decimalYes, if fuelSolution set to ExpertFuel.
vehicle > minFuelLevelMinimum fuel balance required in tenths of gallons.decimalNo
vehicle > minEndingFuelLevelThe minimum fuel level in tenths of gallons required at the end of the trip.integerNo
vehicle > minFuelPurchaseMinimum fuel purchase required in tenths of gallons.integerNo
vehicle > isHighValueVehicle is carrying a high value load.booleanNo, default is False
tspDriverIdThe fleetwide unique identifier of the driver.stringYes
driverHosRuleSetThe hours of service rule set applicable for the driver.stringNo.
driverHoursOfServiceThe hours of service parameters, if using ALK HOS solution.driverHoursOfService objectNo.
driverHoursOfService > EnabledIf false, HOS rest stops will not be inserted in route.booleanNo. Default is true
driverHoursOfService > HoSRuleTypeIndicates 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 “USShortHaul”
HoSRuleType is required to use hours of service calculations if hosSolution is set to 2. Otherwise it is optional.
EnumNo. Default is 1
driverHoursOfService > AlternateHoSRuleTypeIndicates 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 “USShortHaul”
EnumNo. Default is null
driverHoursOfService > RemainingDriveTimeUntilBreakRemaining time in seconds until short break.doubleNo. Default is full HOS.
driverHoursOfService > RemainingDriveTimeRemaining drive time in seconds for the day.doubleNo. Default is full HOS.
driverHoursOfService > RemainingOnDutyTimeRemaining on duty time in seconds for the day.
For Canada HOS this is the remaining time in seconds for a work shift.
doubleNo. Default is full HOS.
driverHoursOfService > RemainingCycleDutyTimeRemaining time in seconds until cycle limit.doubleNo. Default is full HOS.
driverHoursOfService > RemainingCanadaOnDutyTimeRemaining time in seconds for a day - applicable only for Canada HOS.doubleNo. Default is full HOS.
driverHoursOfService > RemainingTimeUntilFullDayBreakRemaining time in seconds until a full day (24-hour) break is needed - applicable only for Canada Cycle Two HOS.doubleNo. Default is full HOS.
driverHoursOfService > RemainingTimeUntilFullDayBreakDriver2Remaining time in seconds until a full day (24-hour) break is needed for driver2 - applicable only for Canada Cycle Two HOS.doubleNo. Default is full HOS.
driverHoursOfService > CycleTimeGainsAn array of cycle time gains in seconds for the next 6 or 7 days.doubleNo. Default is no cycle time gains.
driverHoursOfService > LastCycleResetDateTimeDate and time of end of last cycle reset - applicable only for Canada HOSstringNo.
driverHoursOfService > Last24HourBreakDateTimeDate and time of end of last 24 hour break - applicable only for Canada HOSstringNo.
driverHoursOfService > remainingDriveTimeUntilBreakDriver2Remaining time in seconds until short break for Driver 2. Used only for Team Driving.doubleNo. Default is full HOS.
driverHoursOfService > remainingDriveTimeDriver2Remaining drive time in seconds for the day for Driver 2. Used only for Team Driving.doubleNo. Default is full HOS.
driverHoursOfService > remainingOnDutyTimeDriver2Remaining 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.doubleNo. Default is full HOS.
driverHoursOfService > remainingCycleDutyTimeDriver2Remaining time in seconds until cycle limit for Driver 2. Used only for Team Driving.doubleNo. Default is full HOS.
driverHoursOfService > cycleTimeGainsDriver2An array of cycle time gains in seconds for the next 6 or 7 days for Driver 2. Used only for Team Driving.doubleNo. Default is full HOS.
driverHoursOfService > lastCycleResetDateTimeDriver2Date and time of end of last cycle reset for Driver 2. Used only for Team Driving. Applicable only for Canada HOSstringNo.
driverHoursOfService > last24HourBreakDateTimeDriver2Date and time of end of last 24 hour break for Driver 2. Used only for Team Driving. Applicable only for Canada HOSstringNo.
driverHoursOfService > remainingCanadaOnDutyTimeDriver2Remaining time in seconds for a day - applicable only for Canada HOS for Driver 2. Used only for Team Driving.doubleNo. Default is full HOS.
driverHoursOfService > UseCycleResetIf true, a cycle reset break will be inserted in route.booleanNo. Default is false.
driverHoursOfService > TerminalDayStartTimeStart of the 24-hour period for the driver for cycle time limit compliancestringNo. Default is midnight in the time zone of the trip origin
driverHoursOfService > UseCustomPlacesIf true, custom locations will be used where possible for HOS rest break.booleanNo. Default is false
driverHoursOfService > TeamDrivingIf true, team driving will be used and, whenever possible, the active driver will be switched instead of taking a rest break.booleanNo. Default is false
driverHoursOfService > activeDriverFor Team Driving, indicates which driver is active at the beginning of the trip.integerNo.
driverHoursOfService > CustomBreakDurationsLonger custom durations for rest stops will be used instead of mandated minimum durations by default.CustomBreakDurationsobjectNo.
driverHoursOfService > CustomBreakDurations > ShortBreakDurationCustom duration in minutes for short rest break instead of mandated minimum 30 minutes.doubleNo.
driverHoursOfService > CustomBreakDurations > EndOfDutyBreakDurationCustom duration in minutes for end of duty break instead of mandated minimum 10 hours.doubleNo.
driverHoursOfService > CustomBreakDurations > CycleResetBreakDurationCustom duration in minutes for cycle reset instead of mandated minimum 34 hours (US) and 36 hours (Canada).doubleNo.
driverHoursOfService > CustomBreakDurations > DriverSwitchBreakDurationCustom duration in minutes for driver switch instead of default minimum of 5 minutes.doubleNo.
driverHoursOfService > CustomBreakDurations > BorderCrossingWaitDurationCustom duration in minutes for border crossing instead of default minimum of 1 hour.doubleNo.
driverHoursOfService > MaxAlternateRestStopsThe maximum number of alternate rest stops that will be returned in the Hours of Service report.integerNo, default is 0.
routingProfileA routingProfile object containing parameters that impact routing.RoutingProfileobjectNo
routingProfile > routingTypeIndicates the routing algorithm to use.
Practical, Shortest, Fastest
stringNo, default is Practical
routingProfile > vehicleTypeThe vehicle type.
Auto, LightDuty, MidsizeTruck, Truck
stringNo, default is Truck
routingProfile > truckDimensionsThe truck style.
NoRestriction, SemiTrailer48, TrailerOrTwins53, DoubleTrailers28, StraightTruck40, Custom, ConventionalSchoolBus, SmallSchoolBus
stringNo, default is NoRestriction
routingProfile > unitsOfMeasureThe units of measure for truck dimensions and weight.
English, Metric
stringNo, default is English.
routingProfile > totalLengthThe total length of the truck. 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.
decimalNo
routingProfile > totalWeightThe gross vehicle registered weight of the truck.decimalNo
routingProfile > maxHeightThe maximum height of the truck. Used when truckDimensions is set to Custom.decimalNo
routingProfile > maxWidthThe maximum width of the truck. Used when truckDimensions is set to Custom.decimalNo
routingProfile > numAxlesVehicle number of axles.
Acceptable values are 2 through 14.
integerNo, default is 5.
routingProfile > LCVIndicates whether the truck is a multi-trailer or longer combination vehicle.booleanNo, default is False.
routingProfile > hazmatTypeIndicates the hazardous material type.
None, General, Explosives, Inhalants, Radioactive, Caustic, Flammable
stringNo, default is None.
routingProfile > tollDiscouragedTrue for avoiding toll roads, False for not avoiding toll roads.booleanNo, default is False
routingProfile > bordersOpenTrue to allow international border crossings, False to avoid or reduce number of international border crossings.booleanNo, default is True
routingProfile > classOverridesIndicates preference for National Network and 53’ (includes state designations) for routing.
None, FiftyThreeFoot, NationalNetwork
stringNo, default is None
routingProfile > elevationLimitThe elevation limit to use during routing.integerNo
routingProfile > isFerryDiscouragedTrue if ferry routes are discouraged during routing, false otherwise.booleanNo, default is false.
routingProfile > useAvoidFavorsTrue if custom avoid favors set up for the fleet with ALK are to be used, false otherwise.booleanNo, default is false.
routingProfile > governorSpeedLimitMaximum speed that the driver is permitted to use in the vehicle.booleanNo.
routingProfile > distanceUnitsIndicates which Distance Units the Trip Distance and Leg Distance will use.
0 or “Miles”
1 or “Kilometers”
enumNo.
routingProfile > useSitesUsed to enable or disable Site routing.booleanNo.
sendOptions > adherenceLevelHow strictly CoPilot routes the driver back to the planned route path.
Valid inputs are Strict, Moderate, None. The sendOptions object is used for the CoPilot integration.
integer
sendOptions > offRouteThresholdThe distance from the planned route path at which the vehicle is considered off route, triggering Route Compliance behavior. The maximum value is 100. This parameter is used for the CoPilot integration.doubleNo, default value is 1 mile when not supplied.
sendOptions > originThresholdThe distance from the planned origin location to the vehicle’s actual location at the start of the trip at which the vehicle is considered far enough to trigger exception notification to the dispatcher.
The maximum value is 100.
doubleNo, default value is 5 miles when not supplied.
sendOptions > governorSpeedThe maximum speed the vehicle is allowed to travel. Format is miles per hour X10 (example 35 mph = 350).doubleNo.
allowDriverToDeclineTripIf true, driver can decline trip in CoPilot.booleanNo.
oocThresholdThe distance from the planned route path at which the vehicle is considered out of corridor.
The maximum value is 100.
doubleNo, default value is 1 mile when not supplied.
afSetIdsAvoid 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
afSetNamesAvoid 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

FieldDescriptionType
alkTripIdThe unique identifier for the trip. This value will be used in subsequent calls to the service pertaining to this trip.integer
nameA display name for this trip.string
tmsTripIdThe trip ID in your planning system. This can be used to match a Trip Management trip with a trip in your database.string
tripStatusThe 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 InProgress, Canceled, Completed, or Declined.string
actualStartDateThe date and time when the accepted the trip in CoPilot.date
tripDistanceThe total mileage of the trip.integer
tripDurationThe total duration of the trip.integer
tripDriveDurationThe total duration of the trip which was spent driving.integer
tripCostThe total cost value for the trip.integer
tripTollsThe total tolls value for the trip.integer
regionIndicates which region was set to run the trip.Enum
stopThe stop array contains every customer stop in the trip plan as well as inserted fuel and rest stops.Array <Stop>
stop > stopSequenceThe order in which the stops are to be executed. This includes inserted fuel and rest stops.integer
stop > stopStatusStatus of the stop
Open,Completed,Canceled,NotViable
string
stop > stopArrivalStatusStatus of the stop
OnTime,AtRisk,Late,Early,NotViable
string
stop > currentETAThe date and time when CoPilot predicts it will be at this stop.date
stop > actualArrivalTimeThe date and time when the driver reached this stop.date
stop > actualDepartureTimeThe date and time when the driver left this stop.date
stop > actualDurationThe number of minutes the driver spent at this stop.integer
stop > stopTypeType of stop
Origin, Work, Waypoint, FuelStop, RestStopShort, RestStopLong, RestStopCycleReset, Destination, RestStopFullDay, RestStopDriverSwitch
string
stop > amenitiesAn array containing the Amenities available as this rest stop.Array <string>
stop > truckServicesIndicates whether this rest stop has Truck Services or not.boolean
stop > activeDriverFor Team Driving, indicates which driver is actively driving starting at this stop.integer
stop > locationEach stop array must have at least two location elements in it.Location object
stop > location > addressAn address object representing the street address, city, state, and postal code of a stop.Address object
stop > location > address > streetAddressThe street address of this trip stop.string
stop > location > address > cityThe city of this trip stop.string
stop > location > address > stateThe state of this trip stop.string
stop > location > address > zipThe zip/postal code of this trip stop.string
stop > location > address > countyThe county where this trip stop is located.string
stop > location > coordsContains the latitude and longitude of the stop.coords object
stop > location > coords > latThe latitude of the stop.string
stop > location > coords > lonThe longitude of the stop.string
stop > location > labelA display name for this trip stop.string
stop > plannedETAEstimated 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.date
stop > plannedDepartureTimeEstimated date and time of departure at the stop as of the initial trip plan when dispatched to the vehicle. The value is formatted in ISO-8601 format.date
stop > plannedDurationThe estimated duration at stop in minutes.integer
stop > saveRestStopIf true, this rest stop will be preserved when recalculating the route.boolean
stop > legDistanceDistance to the next stop in miles.double
stop > legDriveDurationDuration to the reach the next stop in minutes.double
alternateRestStopA list of alternate Hours of Service rest stops that may be used to replace the current rest stopArray <AlternateHosLocation>
alternateRestStops > amenitiesAn array containing the Amenities available as this rest stop.Array <string>
alternateRestStops > truckServicesIndicates whether this rest stop has Truck Services or not.boolean
alternateRestStops > activeDriverFor Team Driving, indicates which driver is actively driving starting at this stop.integer
alternateRestStops > locationThe location of the alternate rest stop.Location object
alternateRestStops > location > addressAn address object representing the street address, city, state, and postal code of the alternate rest stop.Address object
alternateRestStops > location > address > streetAddressThe street address of the alternate rest stop.string
alternateRestStops > location > address > cityThe city of the alternate rest stop.string
alternateRestStops > location > address > stateThe state of the alternate rest stop.string
alternateRestStops > location > address > zipThe zip/postal code of the alternate rest stop.string
alternateRestStops > location > address > countyThe county where the alternate rest stop. is located.string
alternateRestStops > location > coordsContains the latitude and longitude of the alternate rest stop.coords object
alternateRestStops > location > coords > latThe latitude of the alternate rest stop.string
alternateRestStops > location > coords > lonThe longitude of the alternate rest stop.string
alternateRestStops > location > labelA display name for the alternate rest stop.string
hoursOfServiceRemainingRemaining HOS parameters at the end of the trip, if using ALK HOS solution.hoursOfServiceRemaining object
hoursOfServiceRemaining > enabledIndicates whether the trip was run with HOS enabled allowing rest stops insertion.boolean
hoursOfServiceRemaining > remainingDriveTimeUntilBreakRemaining time in seconds until short break at the end of the trip.double
hoursOfServiceRemaining > remainingDriveTimeRemaining drive time in seconds for the day at the end of the trip.double
hoursOfServiceRemaining > remainingOnDutyTimeRemaining 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 > hoSRuleTypeIndicates which HOS Rule was used to run the trip.Enum
hoursOfServiceRemaining > alternateHoSRuleTypeIndicates an alternate hours of service rule type to follow whe making cross border moves between Canada and the United States.Enum
hoursOfServiceRemaining > remainingCycleDutyTimeRemaining time in seconds until cycle limit at the end of the trip.double
hoursOfServiceRemaining > cycleTimeGainsAn array of cycle time gains in seconds for the next 6 or 7 days at the end of the trip.double
hoursOfServiceRemaining > lastCycleResetDateTimeDate and time of end of last cycle reset at the end of the trip - applicable only for Canada HOS.string
hoursOfServiceRemaining > last24HourBreakDateTimeDate and time of end of last 24 hour break at the end of the trip - applicable only for Canada HOS.string
hoursOfServiceRemaining > remainingCanadaOnDutyTimeRemaining time in seconds for a day at the end of the trip - applicable only for Canada HOS.double
hoursOfServiceRemaining > remainingTimeUntilFullDayBreakRemaining 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 > remainingTimeUntilFullDayBreakDriver2Remaining 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 > remainingDriveTimeUntilBreakDriver2Remaining time in seconds until short break at the end of the trip for Driver 2. Used only for Team Driving.double
hoursOfServiceRemaining > remainingDriveTimeDriver2Remaining drive time in seconds for the day at the end of the trip for Driver 2. Used only for Team Driving.double
hoursOfServiceRemaining > remainingOnDutyTimeDriver2Remaining 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 > remainingCycleDutyTimeDriver2Remaining time in seconds until cycle limit at the end of the trip for Driver 2. Used only for Team Driving.double
hoursOfServiceRemaining > cycleTimeGainsDriver2An 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
hoursOfServiceRemaining > lastCycleResetDateTimeDriver2Date 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 > last24HourBreakDateTimeDriver2Date 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 > remainingCanadaOnDutyTimeDriver2Remaining 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
driverHoursOfServiceThe hours of service parameters, if using ALK HOS solution.driverHoursOfService object
driverHoursOfService > useCycleResetIf true, a cycle reset break is inserted in route.boolean
driverHoursOfService > enabledIf false, HOS rest stops are not inserted in route.boolean
driverHoursOfService > terminalDayStartTimeStart of the 24-hour period for the driver for cycle time limit compliance.string
driverHoursOfService > remainingDriveTimeUntilBreakRemaining time in seconds until short break at the end of the trip.double
driverHoursOfService > useCustomPlacesIf true, custom locations are used where possible for HOS rest break.boolean
driverHoursOfService > remainingDriveTimeRemaining drive time in seconds for the day at the end of the trip.double
driverHoursOfService > teamDrivingIf true, team driving will be used and, whenever possible, the active driver will be switched instead of taking a rest break.boolean
driverHoursOfService > remainingOnDutyTimeRemaining 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 > customBreakDurationsLonger custom durations for rest stops are used instead of mandated minimum durations by default.CustomBreakDurations object
driverHoursOfService > hoSRuleTypeIndicates which hours of service rule type was followed.Enum
driverHoursOfService > alternateHoSRuleTypeIndicates an alternate hours of service rule type followed when making cross border moves between Canada and the United States.Enum
driverHoursOfService > remainingCycleDutyTimeRemaining time in seconds until cycle limit at the end of the trip.double
driverHoursOfService > maxAlternateRestStopsThe maximum number of alternate rest stops that will be returned in the Hours of Service report.integer
driverHoursOfService > cycleTimeGainsAn array of cycle time gains in seconds for the next 6 or 7 days at the end of the trip.double
driverHoursOfService > lastCycleResetDateTimeDate and time of end of last cycle reset at the end of the trip - applicable only for Canada HOS.string
driverHoursOfService > last24HourBreakDateTimeDate and time of end of last 24 hour break at the end of the trip - applicable only for Canada HOS.string
driverHoursOfService > remainingCanadaOnDutyTimeRemaining time in seconds for a day at the end of the trip - applicable only for Canada HOS.double
driverHoursOfService > remainingDriveTimeUntilBreakDriver2Remaining time in seconds until short break at the end of the trip for Driver 2. Used only for Team Driving.double
driverHoursOfService > remainingDriveTimeDriver2Remaining drive time in seconds for the day at the end of the trip for Driver 2. Used only for Team Driving.double
driverHoursOfService > remainingOnDutyTimeDriver2Remaining 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 > remainingCycleDutyTimeDriver2Remaining time in seconds until cycle limit at the end of the trip for Driver 2. Used only for Team Driving.double
driverHoursOfService > cycleTimeGainsDriver2An 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 > lastCycleResetDateTimeDriver2Date 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 > last24HourBreakDateTimeDriver2Date 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 > remainingCanadaOnDutyTimeDriver2Remaining 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
afSetIdsAvoid or favor set Ids are used for routing.Array <string>
afSetNamesAvoid 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"
    }
  },
  "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",
      "stopSequence": 0
    },
    {
      "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",
      "stopSequence": 0
    },
    {
      "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",
      "stopSequence": 0
    },
    {
      "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",
      "stopSequence": 0
    }
  ],
  "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": false,
    "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",
  "driverHosRuleSet": null,
  "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": false,
    "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,
  "alkTripId": 136
}

Error Conditions

FieldDescriptionTypeValues
ErrorTypeThe type of error that occurred.stringArgumentException - 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.
DescriptionAn error message describing what occurred.stringThis 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.
ErrorCodeA 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
}