Skip to main content

Vehicle Service Time

A node's service_time says how long the stop takes. Sometimes that depends on the vehicle as well as the stop: a large truck needs longer to park and open up than a van, and a vehicle without a tail lift is slower to unload. Vehicle service time adds a vehicle-dependent amount on top of each node's own service_time whenever that vehicle serves the node.

Two components​

Set service_time on the vehicle. Both components are optional and can be combined.

FieldAddedUse it for
additive_per_nodeto every node the vehicle serveswork repeated for each order, such as unloading one order's goods
additive_per_locationonce per location the vehicle visitswork done once per stop, such as parking or opening the cargo door

For additive_per_location, consecutive nodes at the same coordinates count as one location, and the time is added to the last node before the vehicle moves on.

Each component is either:

  • a number of seconds, applied to every node, or
  • an object with separate pickup and dropoff values. Only pickup and dropoff nodes are charged; a key that is omitted or null adds nothing.

Values must be 0 or greater. Any other key is rejected.

"service_time": {
  "additive_per_node": 60,
  "additive_per_location": { "pickup": 300, "dropoff": 120 }
}

With this setting, a vehicle that delivers three orders to the same address spends each order's own service_time, plus 60 seconds per order, plus 120 seconds once for the address.

Stateless API​

Set service_time on each vehicle in the request. The number form of additive_per_node applies to every non-depot node, including waypoints. Depot nodes are not charged by additive_per_location either.

When several orders are merged into one node, set the node's additive_per_node_vehicle_service_time_multiplier to the number of orders it stands for, so additive_per_node is charged once per order instead of once per merged node. See the Stateless API reference for the full schema.

Integration API​

service_time is a field of both the vehicle and the vehicle type, null by default.

  • Inheritance: a vehicle created with a vehicle_type and no service_time of its own takes the type's value when it is created. Changing the type afterwards does not update existing vehicles.
  • Bulk tasks: the bulk vehicle upload accepts service_time; the bulk vehicle update does not.
  • Where it applies: it is sent to the optimization engine with the vehicle, and manual edits apply it too whenever they reschedule a route. When grouped orders are sent as one node, SWAT sets the multiplier to the group size for you.
  • Result: each node stores the service time it was actually scheduled with, vehicle service time included, in the read-only scheduled_service_time. It is reset to null when the node is unassigned.

POST /api/v2/microservices/calculate_scheduled_ts takes the vehicle's settings as vehicle_service_time and returns the resulting estimated_service_time for each node. There, the number form of additive_per_node applies to every node in the sequence you send.