Modify Trip

Trip Management’s Modify Trip API lets you update a previously generated route. Using this API replaces the corresponding fields in the existing trip (stops, planned start time or location, vehicle and routing profile).

If the trip is InProgress, you cannot modify the planned start time or location, vehicle, routing profile, or any stop that has been completed.

If the trip is Completed or Canceled, you cannot modify any part of the trip. Call the recalculate trip API after modifications are done to generate the new optimized trip.

PUT /trip/modify

Request Fields

FieldDescriptionTypeRequired
tripIdThe 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 modified. In this case, if no trip is found with the given tmsTripId, then an error message will be returned.
integerYes if tmsTripId is not supplied.
tmsTripIdThe 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 modified. If no trip is found with the given tmsTripId, then an error message will be returned.
stringYes if tripId is not supplied.
nameA display name for this trip.stringNo, include only if it is different from the original value
plannedStartTimeSame as the plannedStartTime in PlanTrip API.dateNo, include only if it is different from the original value
plannedStartLocationSame as the plannedStartLocation in PlanTrip API.Coords objectNo, include only if it is different from the original value
vehicleSame as the vehicle in PlanTrip API.Vehicle objectNo, include only if it is different from the original value
hosSolutionIndicates whether or not to insert rest stops along the route
0 = do not insert rest stops, 1 = insert rest stops using ETAPTA (if licensed), 2 = insert rest stops using Trimble data
integerNo, default is O
routingProfileSame as the routingProfile in PlanTrip API.RoutingProfile objectNo, include only if it is different from the original value
stopsSame as the stop array in PlanTrip API. If included, replaces the entire stop array of the trip. So send the whole array of stops including the completed stops. Retrieve the current stop array by calling the GetTrip API for accurate modification.

To delete a stop, remove the stop object from the planned stop array and send the remaining stops.

To add a stop, insert the stop object in the expected position of the planned stop array.

Cannot modify any of the completed stops. Can only modify the stop duration of an Arrived stop.

When this API is called, all fuel stops and HOS rest stops will be recalculated and inserted back into the trip.

Array <Stop>No, include only if the stops are different from the current stop array
stops > stop > saveRestStopIf true, this rest stop will be preserved when recalculating the route. All rest stops that do not have saveRestStop=1 will be deleted and recalculated.booleanNo

Response Fields

FieldDescriptionType
successTrue if the route was sent successfully; false if not.boolean
messageContains the reason the message was not sent if success = false.string

Sample Request

{
  "tripId": "136",
  "plannedStartTime": "2017-09-21T14:11:52.522Z",
  "plannedStartLocation": {
    "Coords": {
      "Lat": "42.346619",
      "Lon": "-71.096961"
    }
  },
  "stops": [
    {
      "Location": {
        "Address": {
          "StreetAddress": "4 Yawkey Way",
          "City": "Boston",
          "State": "MA",
          "Zip": "02215",
          "County": "Suffolk"
        },
        "Label": "Fenway Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "stopType": "Origin",
      "stopSequence": 0
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "1000 Ballpark Way",
          "City": "Arlington",
          "State": "TX",
          "Zip": "76011"
        },
        "Label": "Globe Life Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "atRiskThreshold": 30,
      "stopType": "Work",
      "stopSequence": 0
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "100 Park Blvd",
          "City": "San Diego",
          "State": "CA",
          "Zip": "92101"
        },
        "Label": "Petco Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "atRiskThreshold": 30,
      "stopType": "Destination",
      "stopSequence": 0
    }
  ],
  "routingProfile": {
    "name": "example_profile_1",
    "LCV": false,
    "bordersOpen": true,
    "classOverrides": "NationalNetwork",
    "elevationLimit": null,
    "hazmatType": "None",
    "isFerryDiscouraged": false,
    "maxHeight": 180,
    "maxWidth": 96,
    "numAxles": 2,
    "routingType": 0,
    "tollDiscouraged": false,
    "totalLength": 240,
    "totalWeight": 9000,
    "truckDimensions": 16,
    "unitsOfMeasure": 0,
    "vehicleType": 3
  },
  "vehicle": {
    "tspVehicleId": "111111",
    "fuelNetworkId": "P",
    "fuelPlanId": "545345",
    "fuelTankCapacity": 350,
    "fuelTankLevel": 200,
    "milesPerGallon": 5.5,
    "minFuelLevel": 50,
    "minEndingFuelLevel": 100
  }
}

Sample Request 2

{
  "tripId": "136",
  "plannedStartLocation": {
    "Coords": {
      "Lat": "42.346619",
      "Lon": "-71.096961"
    }
  },
  "vehicle": {
    "tspVehicleId": "111111",
    "fuelNetworkId": "P",
    "fuelPlanId": "545345",
    "fuelTankCapacity": 350,
    "fuelTankLevel": 200,
    "milesPerGallon": 5.5,
    "minFuelLevel": 50,
    "minEndingFuelLevel": 100
  }
}

Sample Response

{
  "success": true,
  "message": null
}