Get Planned Trip

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

FieldDescriptionTypeRequired
tripIdThe alkTripId returned when you planned the trip.integerYes

GET /trip/planned?tripId={tripId}

Resource URL

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

Request Fields

FieldDescriptionTypeRequired
tripIdThe 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 stringYes

Response Fields

Same response for both the types of requests

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
stopsThe stop array contains every customer stop in the trip plan as well as inserted fuel and rest stops.Array <Stop>
stops > stopSequenceThe order in which the stops are to be executed. This includes inserted fuel and rest stops.integer
stops > stopStatusStatus of the stop
  • Open,
  • Completed,
  • Canceled,
  • NotViable
string
stops > stopArrivalStatusStatus of the stop
  • OnTime,
  • AtRisk,
  • Late,
  • Early,
  • NotViable
string
stops > currentETAThe date and time when CoPilot predicts it will be at this stop.date
stops > actualArrivalTimeThe date and time when the driver reached this stop.date
stops > actualDepartureTimeThe date and time when the driver left this stop.date
stops > actualDurationThe number of minutes the driver spent at this stop.integer
stops > stopTypeType of stop
  • Origin,
  • Work,
  • Waypoint,
  • FuelStop,
  • RestStopShort,
  • RestStopLong,
  • RestStopCycleReset,
  • Destination,
  • RestStopFullDay,
  • RestStopDriverSwitch,
  • BorderCrossing
string
stops > amenitiesAn array containing the Amenities available as this rest stop.Array <string>
stops > truckServicesIndicates whether this rest stop has Truck Services or not.boolean
stops > activeDriverFor Team Driving, indicates which driver is actively driving starting at this stop.integer
stops > locationEach stop array must have at least two location elements in it.Location object
stops > location > addressAn address object representing the street address, city, state, and postal code of a stop.Address object
stops > location > address > streetAddressThe street address of this trip stop.string
stops > location > address > cityThe city of this trip stop.string
stops > location > address > stateThe state of this trip stop.string
stops > location > address > zipThe zip/postal code of this trip stop.string
stops > location > address > countyThe county where this trip stop is located.string
stops > location > coordsContains the latitude and longitude of the stop.coords object
stops > location > coords > latThe latitude of the stop.string
stops > location > coords > lonThe longitude of the stop.string
stops > location > labelA display name for this trip stop.string
stops > 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
stops > 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
stops > plannedDurationThe estimated duration at stop in minutes.integer
stops > saveRestStopIf true, this rest stop will be preserved when recalculating the route.boolean
stops > legDistanceDistance to the next stop in miles.double
stops > legDriveDurationDuration to the reach the next stop in minutes.double
alternateRestStopsA 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 the Trimble MAPS 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.Array <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 > remainingTimeUntilFullDayBreakFor Canada Cycle Two HOS this is the available hours at origin until a full day (24-hour) break is needed.double
hoursOfServiceRemaining > remainingTimeUntilFullDayBreakDriver2For Canada Cycle Two HOS this is the available hours at origin for Driver2 until a full day (24-hour) break is needed.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.Array <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 the Trimble MAPS 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, HOS rest stops are not inserted, as team driving rules are not yet supported.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.Array <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 > remainingTimeUntilFullDayBreakFor Canada Cycle Two HOS this is the available hours at origin until a full day (24-hour) break is needed.double
driverHoursOfService > remainingTimeUntilFullDayBreakDriver2For Canada Cycle Two HOS this is the available hours at origin for Driver2 until a full day (24-hour) break is needed.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.Array <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 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
}