RESTful APIs

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

Field Description Type Required
tmsId Indicates 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
tspId Telematics Solutions or MobilComm Provider ID provided by Trimble Maps. 
string
No
tmsTripId The trip ID (Load ID or Order number) in the TMS system. 
string
No
tmsCustomerId The customer or company ID in the TMS system - client who purchased the Trip Management Solution. 
string
No
tmsUserId The user ID in the TMS system. 
string
No
name A display name for this trip that can be used when trip information is shared or displayed. 
string
No
hosSolution Indicates 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
plannedStartTime The 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”.
plannedStartLocation The 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 > lat The latitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits. 
string
No
plannedStartLocation > coords > lon The longitude of the planned start location. Minimum 4 decimal digits required. Desired 6 decimal digits. 
string
No
region Indicates 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

Field Description Type Required
stops The 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 > 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
No. Default is Work
stops > location Each stop array must have either a coords object or address object for location. 
Location object
Yes
stops > location > address An 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 > streetAddress The street address of this trip stop. 
string
Yes, if coords object is not supplied.
stops > location > address > city The 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 > state The state of this trip stop. 
string
Yes, if coords object is not supplied.
stops > location > address > zip The 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 > county The county where this trip stop is located. 
string
No
stops > location > coords Contains the latitude and longitude of the stop. 
Coords object
Yes, if address object is not supplied.
stops > location > coords > lat The latitude of the stop. Minimum 4 decimal digits required. Desired 6 decimal digits. 
string
Yes, if address object is not supplied.
stops > location > coords > lon The longitude of the stop.Minimum 4 decimal digits required. Desired 6 decimal digits. 
string
Yes, if address object is not supplied.
stops > location > label A display name for this trip stop. 
string
No
stops > earliestArrivalTime The 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 > latestArrivalTime The 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 > plannedDuration The time planned to be at the stop location in minutes. Typically also defined as “dwell time.” Dwell times impact the ETAs. 
double
No
stops > atRiskThreshold Threshold 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 > tooEarlyThreshold Threshold 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 15
stops > metadata Notes that can be stored with the stop. These will not be delivered to the driver. 
string
No
stops > saveRestStop If true, this rest stop will be preserved when recalculating the route. 
boolean
No

Vehicle, Driver and Load Details

Field Description Type Required
vehicle The vehicle object contains information about the vehicle. 
Vehicle object
No
vehicle > tspVehicleId The ID for the vehicle assigned to the trip in the telematics providers system. Not actively used within Trip Management API. 
string
No
vehicle > isHighValue Vehicle is carrying a high value load. For informational purposes only. Does not impact route calculation. 
boolean
No, default is False
tspDriverId The 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
externalOrderIds An 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
oocDistanceThreshold The threshold distance at which an Out of Corridor event notification will be triggered. The distance unit is Miles and the value should be greater than 0. 
decimal
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.

Field Description Type Required
routingProfile A routingProfile object containing parameters that impact routing. 
object
No
routingProfile > routingType The 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 > vehicleType The 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 > truckDimensions The 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 > unitsOfMeasure The 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 > totalLength The 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 > totalWeight The 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 > maxHeight The 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 > maxWidth The 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 > numAxles Vehicle number of axles. Only used when truckDimensions is set to Custom.
Acceptable values are 2 through 14. 
integer
No, default is 5.
routingProfile > LCV Indicates whether the truck is a multi-trailer or longer combination vehicle. (North America only) 
boolean
No, default is False.
routingProfile > hazmatType Indicates 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 > tollDiscouraged Set to True to avoid toll roads. Default is False. 
boolean
No, default is False
routingProfile > includeTollData Set to True to return total toll costs for the trip. Default is False 
boolean
No, default is False
routingProfile > bordersOpen Set 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. For EU travel, setting this to False will reduce the number of EU border crossings where possible and the route will follow the best path within the country from which the route originates. 
boolean
No, default is True
routingProfile > classOverrides Indicates preference for National Network and 53’ (includes state designations) for routing. (North America Only)
  • None,
  • FiftyThreeFoot,
  • NationalNetwork 
string
No, default is None
routingProfile > elevationLimit The elevation limit to use during routing. Avoids routes going above defined elevation. (North America Only) 
integer
No
routingProfile > isFerryDiscouraged Set to True to avoid ferries during routing, False otherwise. 
boolean
No, default is False.
routingProfile > useAvoidFavors Set 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 > governorSpeedLimit Maximum 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 > distanceUnits Indicates which Distance Units the Trip Distance and Leg Distance will use.
  • 0 or “Miles”
  • 1 or “Kilometers”
 
enum
No
routingProfile > useSites Another 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 > TunnelRestrictions Tunnel 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
routingProfile > sideOfStreetAdherence How strict to be in order to avoid the destination being on the opposite side of the street.
0 - Off (Default)
1- Minimal
2 - Moderate
3 - Average
4 - Strict
5 - Adhere
6 - StronglyAdhere 
Enum
No, default is Off
afSetIds Avoid 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
afSetNames Avoid 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

Europe Settings for Emissions and Tolls

These settings are specific to Vehicle Routing Profiles in Europe only. They are used to accurately calculate toll costs and greenhouse gas (GHG) emissions.

Field Description Type Required
routingProfile > euProfile > hasTrailer This is not required for every vehicle towing a trailer but it must be set as True in order to configure the following values of euProfile:
  • isHybrid
  • minPoll
  • trailerType
  • emiType
  • trailerCount
  • trailerMaxAxles
  • trailerMaxHt
  • trailerMaxWt
 
boolean
No, default is False.
routingProfile > euProfile > isHybrid Indicates whether the vehicle has a hybrid engine. Used for Toll Detail Reports in Europe. 
boolean
No, default is False.
routingProfile > euProfile > minPoll Indicates whether the vehicle is designated a “minimum pollution vehicle”. Used for Toll Detail Reports in Europe. 
boolean
No, default is False.
routingProfile > euProfile > trailerType Indicates the type of trailer. This and all trailer related information is used primarily in Toll Detail Reports in Europe.
  • 1 - None (Default)
  • 2 - Caravan
  • 3 - Trailer 
enum
No, default is None.
routingProfile > euProfile > emiType Indicates the emission type of the engine. Used for Toll Detail Reports in Europe.
  • 2 - Euro0
  • 3 - EuroI
  • 4 - EuroII
  • 5 - EuroIII
  • 6 - EuroIV
  • 7 - EuroV
  • 8 - EuroVI (Default)
  • 9 - EuroEEV 
enum
No, default is 8 - EuroVI.
routingProfile > euProfile > CO2Class Indicates the emission CO2 class of the vehicle that will be used in routing to determine adjustments to toll costs. This is used in conjunction with the emiType parameter. When emiType of EuroVI used, a CO2Class is required. EuroVI is the default emission type and Class1 is the default CO2Class. If no input is given, both defaults are set.
  • 0 - Unknown
  • 1 - Class1 (Default)
  • 2 - Class2
  • 3 - Class3
  • 4 - Class4
  • 5 - Class5 
enum
Yes, when emiType is set to EuroVI.
routingProfile > euProfile > trailerCount Indicates the number of trailers and semi-trailers. 
integer
No, default is 0.
routingProfile > euProfile > trailerMaxAxles Indicates the maximum number of axles on the trailer. Acceptable values are 1 through 8. Used for Toll Detail Reports in Europe. 
integer
No, default is 1.
routingProfile > euProfile > fuelConsumption Indicates the amount of fuel a vehicle consumes in “liters per 100km.” The format is a floating point number (for example 23.5).

This individual value overrides the default fuel consumption values which are used when this parameter is set to default (0). The default values for fuel consumption are based on UK DEFRA 2018. It provides average fuel consumption by weight class and vehicle setup, which are calculated automatically based on the dimension settings in the vehicle routing profile.

This parameter is used in State and Mileage reports to calculate “Tank-To-Wheel” (TTW), greenhouse gas (GHG) emissions. It is not used for fuel cost calculations. 

double
No, default is 0.
routingProfile > euProfile > refrigerated Indicates whether a truck trailer is refrigerated. This parameter will be used in State and Mileage reports to calculate “Tank-To-Wheel” (TTW) greenhouse gas (GHG) emissions. 
boolean
No, default is False.
routingProfile > euProfile > fuelType Indicates the type of fuel being used. This parameter is used in State and Mileage reports to calculate “Tank-To-Wheel” (TTW) greenhouse gas (GHG) emissions.
  • 0 - FuelType_Petrol
  • 1 - FuelType_Petrol_E5 (5% ethanol by vol)
  • 2 - FuelType_Petrol_E10 (10% ethanol by vol)
  • 3 - FuelType_Ethanol
  • 4 - FuelType_Diesel (Default)
  • 5 - FuelType_Biodiesel
  • 6 - FuelType_Diesel_D5 (5% biodiesel by vol)
  • 7 - FuelType_Diesel_D7 (7% biodiesel by vol) 
enum
No, default is Diesel.

Response Fields

Field Description Type
success True if the route was sent successfully; false if not. 
boolean
message Contains 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
  },
}

Sample Response 

{
  "success": true,
  "message": null
}
Last updated July 8, 2024.
API Endpoint:
AWS Azure
Contents