Skip to main content

Recalculate Trip

Contents

Trip Management’s Recalculate Trip API lets you recalculate the uncompleted portion of the trip. Based on the updated position and HOS, this API will return updated trip details and a revised ETA.

In order to provide the best available ETAs, the Trip Management service automatically recalculates:

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

A Recalculate Trip API call is required when you want to update Hours of Service (HOS) information for the trip. We also recommend calling the Recalculate Trip API when there are other changes to the trip, including:

  • After an Arrived/Departed event. After arriving at and completing a stop, recalculation gets the latest ETA for that driver. Recalculation can help take into account deliveries or rest breaks that are shorter or longer than the allotted time.
  • After an out-of-corridor event when the driver leaves the route or returns to the route. If the driver has left or rejoined the planned route, the ETA will change and needs to be recalculated.

PUT /trip/recalculate

Resource URL

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

Request Fields

Field Description Type Required
tripId The alkTripId returned when you planned the trip.
Note: If no trip is found with the given alkTripId, then an error message will be returned. If the tmsTripId in your planning system is also supplied in the body of this request, then the alkTripId will be ignored irrespective of whether it is valid or not and the trip corresponding to the provided tmsTripId will be recalculated. In this case, if no trip is found with the given tmsTripId, then an error message will be returned.
integer
Yes if tmsTripId is not supplied.
tmsTripId The tmsTripId of your previously generated route.
Note: Even if tripId, which is the alkTripId, is also supplied with this request, it will be ignored and only trip corresponding to the given tmsTripId will be recalculated. If no trip is found with the given tmsTripId, then an error message will be returned.
string
Yes if tripId is not supplied.
currentLocation The current location in latitude/longitude. This will be used as the starting location when recalculating the remainder of the trip.
object
No, default is the last gps point sent through the update position API if available, or the plannedStartLocation of the full trip
currentTime The device time or time the GPS ping was reported. It is used to update ETAs for the remainder of the trip. The value must be in ISO-8601 format.
string
No, however it is recommended to calculate more accurate ETAs.
driverHoursOfService The hours of service parameters, if using the Trimble Maps HOS solution. This field is same as the driverHoursOfService in PlanTrip requestdriverHoursOfService
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 “USShortHaul”
  • 7 or “Europe”
Enum
No. Default is 1
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 “USShortHaul”
  • 7 or “Europe”
Enum
No. Default is null
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.
For Canada HOS this is the remaining time in seconds for a work shift.
double
No. Default is full HOS.
driverHoursOfService > RemainingCycleDutyTime Remaining time in seconds until cycle limit.
double
No. Default is full HOS.
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 full day break - applicable only for Canada Cycle Two HOS.
double
No. Default is full HOS.
driverHoursOfService > RemainingTimeUntilFullDayBreakDriver2 Remaining time in seconds until full day break for driver 2- applicable only for Canada Cycle Two HOS.
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 > 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.
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 > RemainingCanadaOnDutyTimeDriver2 Remaining time in seconds for a day for Driver 2. Used only for Team Driving. Applicable only for Canada HOS.
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 no cycle time gains.
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 > 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. e
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.
driverHoursOfService > UseCycleReset If set to true, a cycle reset break will be inserted in route.
boolean
No. Default is the value provided when the trip was planned using Plan Trip. In Plan Trip calls, UseCycleReset defaults to false if no value is provided.
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
driverHoursOfService > UseCustomPlaces If true, custom locations will be used where possible for HOS rest break.
boolean
No. Default is false
driverHoursOfService > teamDriving (U.S. and Canada Only) If set to true, team driving will be used and, whenever possible, the active driver will be switched instead of taking a rest break. A separate “driver swap” rest break is inserted when a driver’s time is up. The duration of that break is set using driverSwitchBreakDuration, with a default of 5 minutes if no value is entered.


activeDriver determines which driver starts the trip so that the Trip Management service knows whose clock to count down first.

boolean
No. Default is false
driverHoursOfService > activeDriver For Team Driving, indicates which driver is active at the beginning of the trip.
integer
No. Default is 1
driverHoursOfService > CustomBreakDurations Longer custom durations for rest stops will be used instead of mandated minimum durations by default.CustomBreakDurations
object
No.
driverHoursOfService > CustomBreakDurations > ShortBreakDuration Custom duration in seconds for short rest break instead of mandated minimum 30 minutes.
double
No.
driverHoursOfService > CustomBreakDurations > EndOfDutyBreakDuration Custom duration in seconds for end of duty break instead of mandated minimum 10 hours.
double
No.
driverHoursOfService > CustomBreakDurations > CycleResetBreakDuration Custom duration in seconds for cycle reset instead of mandated minimum 34 hours (US) and 36 hours (Canada).
double
No.
driverHoursOfService > CustomBreakDurations > DriverSwitchBreakDuration Custom duration in seconds for driver switch instead of default minimum of 5 minutes.
double
No.
driverHoursOfService > CustomBreakDurations > BorderCrossingWaitDuration Custom duration in seconds for border crossing instead of default minimum of 1 hour.
double
No.
driverHoursOfService > CustomBreakDurations > BreakTimeInDayDuration The custom duration in seconds for reducing the daily rest period. Default daily rest is 11 hours. This can be reduced to 9 hours (32400 seconds) 3 times per week as allowed by Europe HOS.
integer
No - default is 11 hours
driverHoursOfService > CustomBreakDurations > BreakTimeInWeekDuration The custom duration in seconds for reducing the weekly rest period. Default weekly rest is 45 hours. This can be reduced to 24 hours (86400 seconds) as allowed by Europe HOS.
integer
No - default is 45 hours
driverHoursOfService > MaxAlternateRestStops The maximum number of alternate rest stops that will be returned in the Hours of Service report.
boolean
No, default is 0.
driverHoursOfService > CurrentOffDutyTime The amount of off-duty time the driver has already accumulated at the time the trip was created. For example, if a driver is due for an end-of-day break, which is typically 10 hours, HOS logic will reduce that break duration by the amount of time entered in the “CurrentOffDutyTime” parameter.
  • The format is in seconds.
  • double
    No, default is 0.
    driverHoursOfService > CurrentOffDutyTimeDriver2 The amount of off-duty time the driver has already accumulated at the time the trip was created. For example, if a driver is due for an end-of-day break, which is typically 10 hours, HOS logic will reduce that break duration by the amount of time entered in the “CurrentOffDutyTime” parameter.
  • The format is in seconds.
  • Used only for Team Driving.
  • double
    No, default is 0.
    driverHoursOfService > POIStopsReturned Sets whether rest stops are returned as actual stop locations (POIs) along the route or only as the latitude/longitude coordinates for the last point along the route that a rest stop must be taken before a violation occurs.


    When set to False, the lat/lon location will be set 30 minutes before the HOS violation line if HOSwindowStart and HOSwindowEnd are set to default values. If HOSwindowStart and HOSwindowEnd are NOT default, then the lat/lon location will be set at HOSwindowEnd.


    True = Use POIs
    False = Coordinates

    bool
    No - Default is True
    driverHoursOfService > HOSWindowStart Sets the time in minutes prior to when an HOS break is required that the algorithm should start looking for a rest stop to insert in the trip. The value can be between 10 and 60 minutes. For example, if a break is required at 2 p.m., and HOSWindowStart is set to 30, the window for inserting a rest stop begins at 1:30 p.m.
    int
    No - Default is 60
    driverHoursOfService > HOSWindowEnd Sets the time in minutes prior to when an HOS break is required that the algorithm should finish looking for a rest stop to insert in the trip. The value can be between 10 and 60 minutes. For example, if a break is required at 2 p.m., and HOSWindowEnd is set to 10, the window for inserting a rest stop ends at 1:50 p.m. To maximize driving time, the algorithm will look for a stop as close as possible to the end of the window.
    int
    No - Default is 10

    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
    • InProgress,
    • Canceled,
    • Completed, or
    • Declined.
    string
    actualStartDate The date and time when the accepted the trip in CoPilot.
    date
    tripDistance The total mileage of the trip.
    double
    tripDuration The total duration of the trip.
    double
    tripDriveDuration The total duration of the trip which was spent driving.
    integer
    tripCost The total cost value for the trip.
    integer
    tripTolls The total tolls value for the trip.
    integer
    remainingLegDistance The remaining distance in miles or kilometers for the current in-progress leg of the trip. Tracked from the last received GPS ping to the next open stop in the trip
    integer
    remainingLegDuration The remaining duration in minutes for the current in-progress leg of the trip. Tracked from the last received GPS ping to the next open stop in the trip
    integer
    region Indicates which region was set to run the trip.
    Enum
    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 to be executed. This includes inserted fuel and rest stops.
    integer
    stops > stopStatus Status of the stop
    • Open,
    • Completed,
    • Canceled,
    • NotViable
    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 date and time when the driver reached this stop.
    date
    stops > actualDepartureTime The date and time when the driver left this stop.
    date
    stops > actualDuration The number of minutes the driver spent at this stop.
    integer
    stops > stopType The type of stop. Options are: Origin, Work, Waypoint, FuelStop, Destination, Delivery, Pickup, Break, RestStopShort, RestStopLong, RestStopCycleReset, RestStopFullDay, RestStopDriverSwitch, RestStopShortSplittable (EU ONLY), and RestStopLongSplittable (EU ONLY).
    string
    stops > amenities An array containing the Amenities available as this rest stop.
    Array <string>
    stops > truckServices Indicates whether this rest stop has Truck Services or not.
    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.
    date
    stops > plannedDuration The estimated duration at stop in minutes.
    integer
    stops > saveRestStop If true, this rest stop will be preserved when recalculating the route.
    boolean
    stops > legDistance Distance to the next stop in miles.
    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 > 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 (U.S. and Canada Only) If set to true, team driving will be used and, whenever possible, the active driver will be switched instead of taking a rest break. A separate “driver swap” rest break is inserted when a driver’s time is up. The duration of that break is set using driverSwitchBreakDuration, with a default of 5 minutes if no value is entered.


    activeDriver determines which driver starts the trip so that the Trip Management service knows whose clock to count down first.

    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.
    Array <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
    driverHoursOfService > CurrentOffDutyTime The amount of off-duty time the driver has already accumulated at the time the trip was created. For example, if a driver is due for an end-of-day break, which is typically 10 hours, HOS logic will reduce that break duration by the amount of time entered in the “CurrentOffDutyTime” parameter.
  • The format is in seconds.
  • double
    driverHoursOfService > CurrentOffDutyTimeDriver2 The amount of off-duty time the driver has already accumulated at the time the trip was created. For example, if a driver is due for an end-of-day break, which is typically 10 hours, HOS logic will reduce that break duration by the amount of time entered in the “CurrentOffDutyTime” parameter.
  • The format is in seconds.
  • Used only for Team Driving.
  • 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
    driverHoursOfService > POIStopsReturned Sets whether rest stops are returned as actual stop locations (POIs) along the route or only as the latitude/longitude coordinates for the last point along the route that a rest stop must be taken before a violation occurs.


    When set to False, the lat/lon location will be set 30 minutes before the HOS violation line if HOSwindowStart and HOSwindowEnd are set to default values. If HOSwindowStart and HOSwindowEnd are NOT default, then the lat/lon location will be set at HOSwindowEnd.


    True = Use POIs
    False = Coordinates

    bool
    driverHoursOfService > HOSWindowStart Sets the time in minutes prior to when an HOS break is required that the algorithm should start looking for a rest stop to insert in the trip. The value can be between 10 and 60 minutes. For example, if a break is required at 2 p.m., and HOSWindowStart is set to 30, the window for inserting a rest stop begins at 1:30 p.m.
    int
    driverHoursOfService > HOSWindowEnd Sets the time in minutes prior to when an HOS break is required that the algorithm should finish looking for a rest stop to insert in the trip. The value can be between 10 and 60 minutes. For example, if a break is required at 2 p.m., and HOSWindowEnd is set to 10, the window for inserting a rest stop ends at 1:50 p.m. To maximize driving time, the algorithm will look for a stop as close as possible to the end of the window.
    int
    afSetIds Avoid or favor set Ids are used for routing.
    Array <integer>
    afSetNames Avoid or favor set names are used for routing.
    Array <string>

    Sample Request

    {
      "tripId": "136",
      "currentLocation": {
        "Coords": {
          "Lat": "42.346619",
          "Lon": "-71.096961"
          },
          "Label":"Current Location"
        },
        "currentTime":"2018-07-01T09:00:00-04:00"
    }
      "driverHoursOfService": {
        "hosRuleType": "USFed607LH",
        "remainingDriveTime": 39600,
        "remainingOnDutyTime": 50400,
        "remainingDriveTimeUntilBreak": 28800,
        "remainingCycleDutyTime": 216000,
        "cycleTimeGains": [
          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

    (Same response as Plan Trip and Get Trip APIs)

    {
      "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",
        "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
    }
    
    Last updated July 23, 2024.
    API Endpoint:

    Contents