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

Request Fields

FieldDescriptionTypeRequired
tripIdThe alkTripId returned when you planned the trip.integerYes

GET /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
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, BorderCrossing
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 > 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.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, 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.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.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
}