RESTful APIs

Get Planned Trip (Deprecated)

Trip Management’s Get Planned Trip API gets you the pre-dispatched details of the trip as it was originally planned. This trip does not reflect any changes that were made after the trip was dispatched.

Use this API to analyze the difference between the planned route and the executed route.

Note: When the trip is in pre-dispatched(planned) state, Get Trip API and Get Planned Trip API will return the same trip information.

The following two variations of requests are supported for this functionality:

GET /trip/{tripId}/planned

Resource URL

https://tripmanagement.alk.com/api/trip/{tripId}/planned

Request Fields

Field Description Type Required
tripId The alkTripId returned when you planned the trip. 
integer
Yes

GET /trip/planned?tripId={tripId}

Resource URL

https://tripmanagement.alk.com/api/trip/planned?tripId={tripId}

Request Fields

Field Description Type Required
tripId The alkTripId returned when you planned the trip or the tmsTripId in your planning system.
Note: Only one can be used when making a request through the URL. The search logic will check for the user’s trips with matching tmsTripId. If no trips are found with provided tmsTripId, then the check will continue for trips with matching alkTripId. If no trip is found matching with either of the Trip IDs, then no trip found response will be returned. 
integer
or 
string
Yes

Response Fields

Same response for both the types of requests

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 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
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 > plannedDepartureTime Estimated 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
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 > remainingTimeUntilFullDayBreak For Canada Cycle Two HOS this is the available hours at origin until a full day (24-hour) break is needed. 
double
hoursOfServiceRemaining > remainingTimeUntilFullDayBreakDriver2 For Canada Cycle Two HOS this is the available hours at origin for Driver2 until a full day (24-hour) break is needed. 
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
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 > remainingTimeUntilFullDayBreak For Canada Cycle Two HOS this is the available hours at origin until a full day (24-hour) break is needed. 
double
driverHoursOfService > remainingTimeUntilFullDayBreakDriver2 For Canada Cycle Two HOS this is the available hours at origin for Driver2 until a full day (24-hour) break is needed. 
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
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 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",
    "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 January 30, 2023.