Skip to main content

Modify Trip

Contents

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). Once a trip is edited, the trip automatically recalculates to update ETAs and rest stops, if necessary.

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.

After modifying a trip, call Get Trip to view the updated trip.

PUT /trip/modify

Resource URL

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

Request Fields

Trip Identifiers

FieldDescriptionTypeRequired
tmsIdIndicates which TMS type that the trip will use. This value can only be set in PlanTrip and is not nullable. Please pass with a value or omit the field.
  • 0 or “None”
  • 1 or “TMWSuite”
  • 2 or “ALK”
Enum
No, not nullable
tspIdTelematics Solutions or MobilComm Provider ID provided by Trimble MAPS.
string
No
tmsTripIdThe trip ID (Load ID or Order number) in the TMS system.
string
No
tmsCustomerIdThe customer or company ID in the TMS system - client who purchased the Trip Management Solution.
string
No
tmsUserIdThe user ID in the TMS system.
string
No
nameA display name for this trip that can be used when trip information is shared or displayed.
string
No
hosSolutionIndicates whether or not to insert rest stops along the route
  • 0 = do not insert rest stops,
  • 2 = insert rest stops using Trimble MAPS
Enum
No, default is 0
plannedStartTimeThe planned start date and time of the trip at the planned start location. The value must be in ISO-8601 format. This time is important in order for ETA calculations to take into account the impact of historical traffic patterns along the route.
String
No, default is “now”.
plannedStartLocationThe planned starting location in latitude > longitude.

The default start location of the trip is the first stop specified. If the user wants to have a dedicated start location, it can be set with this parameter. An example for a start location could be the current location of a truck when accepting a job. In that case, the truck has to drive from the current location (plannedStartLocation) to the first stop specified in the trip.

Coords object
No, default is the location of the first stop
plannedStartLocation > coords > latThe latitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits.
string
No
plannedStartLocation > coords > lonThe longitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits.
string
No
regionIndicates which region to be set for the trip. Must be set unless using the default region, North America (NA).
  • 1 or “AF”
  • 2 or “AS”
  • 3 or “EU”
  • 4 or “NA”
  • 5 or “OC”
  • 6 or “SA”
  • 7 or “ME”
Enum
No. Default is 4 or NA

Stop Locations

FieldDescriptionTypeRequired
stopsThe stop array specifies an array of stops for the route that will be generated. Multiple values (below) can be set for each stop.
Array <Stop>
Yes
stops > stopTypeThe 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
No. Default is Work
stops > locationEach stop array must have either coord object or address object for location.
Location object
Yes
stops > location > addressAn address object representing the street address, city, state, and postal code of a stop.
Address object
Yes, if coords object is not supplied.
stops > location > address > streetAddressThe street address of this trip stop.
string
Yes, if coords object is not supplied.
stops > location > address > cityThe city of this trip stop.
string
Yes, if coords object is not supplied and if zip is not provided in the address object.
stops > location > address > stateThe state of this trip stop.
string
Yes, if coords object is not supplied.
stops > location > address > zipThe zip > postal code of this trip stop.
string
Yes, if coords object is not supplied and if city is not provided in the address object.
stops > location > address > countyThe county where this trip stop is located.
string
No
stops > location > coordsContains the latitude and longitude of the stop.
Coords object
Yes, if address object is not supplied.
stops > location > coords > latThe latitude of the stop. Minimum 4 decimal digits required. Desired 6 decimal digits.
string
Yes, if address object is not supplied.
stops > location > coords > lonThe longitude of the stop.Minimum 4 decimal digits required. Desired 6 decimal digits.
string
Yes, if address object is not supplied.
stops > location > labelA display name for this trip stop.
string
No
stops > earliestArrivalTimeThe start of the arrival time window at the stop. The value must be in ISO-8601 format. During the trip, this time is monitored and a notification is provided if the calculated arrival time is earlier than the defined time.
string
No
stops > latestArrivalTimeThe end of the arrival time window at the stop. The value must be in ISO-8601 format. During the trip, this time is monitored and a notification is provided if the calculated arrival time is later than the defined time.
string
No
stops > plannedDurationThe time planned to be at the stop location in minutes. Typically also defined as “dwell time.” Dwell times impact the ETAs.
double
No
stops > atRiskThresholdThreshold can be set in minutes and is monitored during execution. If the calculated ETA is within the defined time window but falls into the threshold, an “At Risk” notification is triggered.

For example, if set to 20 minutes, and the delivery window is from 1pm-3pm, the stop is At Risk if the ETA is anywhere between 2:40pm and 3:00pm. The stop is On Time if ETA is prior to 2:40pm, and Late if ETA is after 3:00pm.

integer
No, default is 15
stops > tooEarlyThresholdThreshold can be set in minutes and is monitored during execution. If the calculated ETA falls into the threshold before the earliestArrivalTime, a “Too Early” notification is triggered. For example, if set to 20 minutes, and the delivery window is from 1pm-3pm, the stop is “Too Early” if the ETA is anytime before 12:40pm.
integer
No, default is a high number
stops > metadataNotes that can be stored with the stop. These will not be delivered to the driver.
string
No

Vehicle, Driver and Load Details

FieldDescriptionTypeRequired
vehicleThe vehicle object contains information about the vehicle.
Vehicle object
No
vehicle > tspVehicleIdThe ID for the vehicle assigned to the trip in the telematics providers system. Not actively used within Trip Management API.
string
No
vehicle > isHighValueVehicle is carrying a high value load. For informational purposes only. Does not impact route calculation.
boolean
No, default is False
tspDriverIdThe fleetwide unique identifier of the driver, vehicle or asset. This field is required when assigning trips to a specific device, driver or vehicle.
string
No
externalOrderIdsAn array of external Order IDs associated with the trip. Max Array Length is 30 and Max Length of each Order ID is 50 characters.
Sample: “externalOrderIds”:[“Order1”,“Order2”,“Order3”]. Not actively used within Trip Management API.
Array <string>
No

Vehicle Routing Profile

The Vehicle Routing Profile influences how the route for a specific type of vehicle is calculated. In all cases, our routing algorithm aims for a suitable and legally compliant route. This is determined by the type of vehicle, the vehicle dimensions and the load.

The Routing Profile can only be edited while the trip is in the Planned state. If it is InProgress, it cannot be modified.

FieldDescriptionTypeRequired
routingProfileA routingProfile object containing parameters that impact routing.
object
No
routingProfile > routingTypeThe type of route you want to calculate. We recommend Practical for trucks, which is the default. Practical aims to find a balance between legally compliant, safe and quick. It avoids any roads legally not allowed for the vehicle/dimensions/load; avoids small roads and city centers; and keeps the driver on roads safe for the vehicle, the driver and the community.
  • 0 = Practical,
  • 1 = Shortest,
  • 2 = Fastest
Enum
No, default is Practical
routingProfile > vehicleTypeThe vehicle type. While Trip Management is designed for large trucks, the functionality is also suitable for other vehicles. In addition to the routing type (see above), the vehicle type influences the route path. (A route for a car is different from a route for a large truck.)
  • 0 = Auto,
  • 3 = Truck,
  • 4 = Bus,
  • 11 = LightTruck,
  • 12 = MidsizeTruck
Enum
No, default is Truck
routingProfile > truckDimensionsThe truck style. You can either select a preset truck type (e.g. SemiTrailer48 or EU16Meter) or use the Custom type and define your required truck dimensions individually, using the parameters below. We have predefined the most common truck types with standard height, weight, width, length and number of axles.
  • 0 = NoRestriction,
  • 1 = SemiTrailer48,
  • 2 = TrailerOrTwins53,
  • 3 = DoubleTrailers28,
  • 4 = StraightTruck40,
  • 5 = EU16Meter,
  • 6 = EU18Meter,
  • 7 = EU12Meter,
  • 8 = EU54Foot,
  • 9 = EU61Foot,
  • 10 = EU40Foot,
  • 16 = Custom,
  • 17 = ConventionalSchoolBus,
  • 18 = SmallSchoolBus
Enum
No, default is NoRestriction
routingProfile > unitsOfMeasureThe units of measure for truck dimensions and weight. If you select a truck type with metric values, ensure that you set the units of measure to Metric.
English (Imperial), Metric
string
No, default is English.
routingProfile > totalLengthThe total length of the truck. Only used when truckDimensions is set to 16 = Custom.

For English units, totalLength is entered as inches in decimal format.

  • Minimum - 39 inches
  • Maximum - 1181 inches

For Metric units totalLength is entered as meters in decimal format.
  • Minimum - 1.00 meters
  • Maximum - 30.00 meters
decimal
No
routingProfile > totalWeightThe gross vehicle registered weight of the truck. Only used when truckDimensions is set to 16 = Custom.

For English units, totalWeight is entered as pounds in decimal format.

  • Minimum - 100 pounds
  • Maximum - 155000 pounds

For Metric units totalWeight is entered as kilograms in decimal format.
  • Minimum - 100 kilograms
  • Maximum - 70000 kilograms
decimal
No
routingProfile > maxHeightThe maximum height of the truck. Only used when truckDimensions is set to 16 = Custom.

For English units, maxHeight is entered as inches in decimal format.

  • Minimum - 39 inches
  • Maximum - 197 inches

For Metric units maxHeight is entered as meters in decimal format.
  • Minimum - 1.00 meters
  • Maximum - 5.00 meters
decimal
No
routingProfile > maxWidthThe maximum width of the truck. Only used when truckDimensions is set to 16 = Custom.

For English units, maxWidth is entered as inches in decimal format.

  • Minimum - 39 inches
  • Maximum - 118 inches
For Metric units maxWidth is entered as meters in decimal format.
  • Minimum - 1.00 meters
  • Maximum - 3.00 meters
decimal
No
routingProfile > numAxlesVehicle number of axles. Only used when truckDimensions is set to Custom.
Acceptable values are 2 through 14.
integer
No, default is 5.
routingProfile > LCVIndicates whether the truck is a multi-trailer or longer combination vehicle. (North America only)
boolean
No, default is False.
routingProfile > hazmatTypeIndicates the hazardous material type.
  • None,
  • 1 - General,
  • 2 - Explosives,
  • 3 - Inhalants,
  • 4 - Radioactive,
  • 5 - Caustic,
  • 6 - Flammable,
  • 7 - Harmful to Water
enum
No, default is None or 0
routingProfile > tollDiscouragedSet to True to avoid toll roads. Default is False.
boolean
No, default is False
routingProfile > includeTollDataSet to True to return total toll costs for the trip. Default is False
boolean
No, default is False
routingProfile > bordersOpenSet to True to allow international border crossings, False to avoid or reduce number of international border crossings. For example, if all your stops are in the “lower 48” United States, the resulting route will stay in the United States even if the most practical or shortest route would normally involve some Canadian mileage. (North America Only)
boolean
No, default is True
routingProfile > classOverridesIndicates preference for National Network and 53’ (includes state designations) for routing. (North America Only)
  • None,
  • FiftyThreeFoot,
  • NationalNetwork
string
No, default is None
routingProfile > elevationLimitThe elevation limit to use during routing. Avoids routes going above defined elevation. (North America Only)
integer
No
routingProfile > isFerryDiscouragedSet to True to avoid ferries during routing, False otherwise.
boolean
No, default is False.
routingProfile > useAvoidFavorsSet to True if custom avoids and favors set up for the fleet with Trimble MAPS are to be used. Avoids and favors (collectively called Route Modifiers) is a separate function of the Trimble Maps platform. It allows fleets to define whether to avoid or favor specific roads within the road network. Read more about Route Modifiers.
You can select specific Route Modifiers sets to use in routing by setting the afSetIds or afSetNames parameters.
boolean
No, default is False.
routingProfile > governorSpeedLimitMaximum speed that the driver is permitted to use in the vehicle. The format is in mph or kph based on distanceUnits. This value is used for ETA calculations.
double
No.
routingProfile > distanceUnitsIndicates which Distance Units the Trip Distance and Leg Distance will use.
  • 0 or “Miles”
  • 1 or “Kilometers”
enum
No.
routingProfile > useSitesAnother unique feature of the Trimble Maps platform is the ability for customers to define Sites. With Sites you can define a polygon around a place, define entry and exit gates and capture other valuable information about a location. More information can be found here.
boolean
No, default is False.
routingProfile > TunnelRestrictionsTunnel Restrictions by category specific to Europe. (Europe Only)
  • 0 - None (Default)
  • 8 - TunnelBCDE
  • 9 - TunnelCDE
  • 10 - TunnelDE
  • 11 - TunnelE
Enum
No. Default is None or 0
afSetIdsAvoid or favor set Ids are used for routing. routingProfile > useAvoidFavors must be true in order to utilize avoid or favor sets supplied.
Array <integer>
No, either set ids or names
afSetNamesAvoid or favor set names are used for routing. routingProfile > useAvoidFavors must be true in order to utilize avoid or favor sets supplied.
Array <string>
No, either set ids or names

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"
    }
  },
  "externalOrderIds": ["123", "abc", "123+abc"],
  "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",
  	  "actualDepartureTime":"2017-09-21T14:11:52.522Z",
      "stopStatus": "Completed",
      "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": 1
    },
    {
      "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": 2
    }
  ],
  "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
}
Last updated June 16, 2022.
Contents