Vehicle Start and End Locations

While a system-wide depot generally represents a centralized hub where vehicles load or park, Vehicle Start and End Locations are specialized vehicle constraints that define explicitly where a specific vehicle begins and finishes its shift.

Why are Start and End Locations Important?

In many realistic logistics scenarios, the fleet does not operate out of a single centralized location. By accurately modeling specific start and end locations for each vehicle, the routing engine and dispatcher can compute routes accurately based on:

• Travel Time and Distance: Measuring the initial empty-driving "stem miles" (driving from start location to the first pickup) and the final return journey, ensuring driver shifts constraints are respected based on their actual location.
• Cost Minimization: The optimization accounts for actual travel from specific origins, significantly improving route cost calculations instead of assuming a single system-wide point of origin.
• Dynamic Shift Modeling: Drivers may start from their homes, branch offices, or different specialized hubs depending on the day. Modifying start/end constraints on a dynamic schedule makes simulation and routing reflect real operations.

Common Logistics Use Cases

• Contractor and Freelance Driver Operations: Drivers frequently start routes from their own homes instead of a corporate depot. Applying individual start constraints ensures accuracy in shift duration and travel reimbursement.
• Multi-Hub Operations: A logistics network might have a centralized parking depot but several satellite loading areas. Setting distinct start locations allows dispatchers to allocate vehicles and drivers to satellite hubs correctly.
• One-Way and Point-To-Point Operations: A vehicle might finish its delivery run in a different city or region and should log its shift end precisely where it drops its last load, without being forced to travel back to the origin depot across the city.

How to Set Start and End Locations

Start and end locations can be set in the Integration API (stateful backend) either through manual node creation or efficiently via the bulk vehicle upload API.

1. Manual Node Creation

You can manually assign start and end locations to a vehicle by creating Node objects associated to the vehicle with specific attributes. In the backend API, these control nodes are defined as point node types that use partial_route_index to define whether they are a start or an end constraint.

Parameters Required:

• node_type: Set to "point".
• assigned_vehicle_id: The ID of the vehicle taking this start/end location.
• status: Typically "assigned".
• partial_route_index:
  • Set to 1 for the Start Location (indicates the beginning of the route).
  • Set to -1 for the End Location (indicates the end of the route).
• lat and lon: The geographic coordinates of the start or end location.

Example Payload/Object representation:

{
  "node_type": "point",
  "lat": 1.290270,
  "lon": 103.851959,
  "assigned_vehicle_id": "YOUR_VEHICLE_UUID",
  "partial_route_index": 1, 
  "status": "assigned",
  "scheduled_ts": "2024-05-28T09:00:00Z"
}

2. Bulk Vehicle Upload API

For managing fleet configurations at scale, the Bulk Vehicle Upload API provides dedicated fields to define distinct start and end locations easily by passing column headers in your uploaded CSV/Excel spreadsheet.

During the upload, the backend will automatically translate these tabular columns into their respective start and end control nodes linked to the vehicle profile.

Start Location Columns:

• start_location_name: (String) A recognizable name for the start location (e.g. "Driver John Home").
• start_location_lat: (Float) The latitude coordinate.
• start_location_lon: (Float) The longitude coordinate.
• start_location_code: (String) Optional unique code identifying the start facility.
• Advanced Details: You may also provide start_location_max_slack, start_location_finalization_type, or a specific start_location_transitstop_id for advanced route modelling.

End Location Columns:

• end_location_name: (String) A name for the end location.
• end_location_lat: (Float) The latitude coordinate.
• end_location_lon: (Float) The longitude coordinate.
• end_location_code: (String) Optional code identifying the end facility.

When these fields are configured during bulk upload, routes sent to the Optimization API will seamlessly begin at the vehicle's unique start_location and be constrained to finish at the specific end_location.

How Start and End Node Time Windows Are Set

Both the start node (partial_route_index = 1) and the end node (partial_route_index = -1) are point-type nodes. Their time windows — open_time_ts and close_time_ts — are set automatically by the backend during vehicle creation or bulk upload. Understanding this behaviour is important for ensuring your fleet constraints are correctly applied.

Time Window Assignment Logic

When a vehicle's start or end location node is created (via the Bulk Vehicle Upload API or manual Node creation tied to a vehicle), the backend assigns the following time windows based on the source code in bulkoperations/tasks/vehicle_upload.py:

Node	open_time_ts	close_time_ts	scheduled_ts
Start node (partial_route_index = 1)	vehicle.start_time or simulation.start_time	vehicle.end_time or simulation.end_time	vehicle.start_time or simulation.start_time
End node (partial_route_index = -1)	vehicle.start_time or simulation.start_time	vehicle.end_time or simulation.end_time	vehicle.end_time or simulation.end_time

In other words:

• If the vehicle has its own start_time and end_time fields set, they are used directly.
• Otherwise, the containing simulation's start_time and end_time are used as the fallback.
• Both start and end nodes receive the same open_time_ts / close_time_ts range (the full vehicle shift window from start to end). The scheduled_ts is what differentiates them positionally in the route: the start node is pinned to the beginning of the shift and the end node to the end.

Max Slack

For additional flexibility around when the optimizer must visit the start/end point, you can configure start_location_max_slack and end_location_max_slack (in seconds) on the vehicle. This allows the optimizer to depart slightly later from the start location or arrive slightly earlier at the end location within the time window. The default is 300 seconds (5 minutes).

Implications for Long Simulations

Long Simulation Windows

When the simulation covers a very long time period (e.g., multiple days, weekly simulations, or rolling-horizon windows), the open_time_ts and close_time_ts for both the start and end nodes span the entire simulation window. This means:

• The optimizer has the full simulation duration within which to route the vehicle — it is not constrained to start and finish within a shorter vehicle shift unless the vehicle's own start_time and end_time fields are explicitly set.
• If vehicle.start_time and vehicle.end_time are null, the node time windows can be excessively wide (e.g., 7 days), which may produce unexpected or unrealistic routing solutions.
• For long-running simulations, always set explicit start_time and end_time on each vehicle to ensure the start and end nodes have correctly bounded time windows.

Created via the Simulation Template Workflow

When a simulation (and its vehicles) is created using the Simulation Template workflow, the time adjustment logic described in that document applies before the start/end nodes are assigned their time windows.

Specifically, the template cloning process adjusts:

• vehicle.start_time → shifted to match the new simulation's start_time
• vehicle.end_time → shifted proportionally to the new simulation's duration

As a result, when the start and end nodes are subsequently created (or cloned) for vehicles in the new simulation, their open_time_ts, close_time_ts, and scheduled_ts values will reflect the time-adjusted vehicle shift times, not those of the original template.

Nodes Are Not Automatically Re-created on Cloning

When a simulation is cloned from a template, existing start and end location nodes on the template vehicles are copied as-is and then have their time window fields adjusted according to the simulation's new time window. If the template vehicle contained a start or end node with incorrect or outdated coordinates, those will be copied into the new simulation. Always verify start/end location nodes after cloning from a template if location accuracy is critical.

For the Bulk Vehicle Upload workflow using simulation_template_id or simulation_template_name, start and end nodes are freshly created with the correctly adjusted time windows for the target simulation.

See the Simulation Templates concept page for a full description of the time window adjustment rules that apply during template cloning.