Vehicle data model used in optimization API
Represents and validates UUID string
Current latitude of the vehicle
Current longtitude of the vehicle
assigned_nodes object[]
A list of nodes that have been assigned to a vehicle. If this data is included in the request, the optimization engine will assume that these nodes have already been assigned to a vehicle. This can be an outcome of previous calculations.
Unique identifier of the node
Required for pickup and dropoff nodes. Unique identifier of the booking this node belongs to (used to correlate pickup and dropoff nodes).
Transit stop corresponding to this node.
Latitude of the node
Longtitude of the node
demand objectrequired
The number of ordinary passengers to be transferred or a dictionary where the key is the type of seat (ordinary passenger is "passenger") and the value is the number of seats required.
In Logistics this could be how many tons of goods the vehicle need to pickup/dropoff from this node
Earliest date and time when the node processing can be started.
Latest date and time when the node processing can be started.
Time required for a vehicle to be serviced (loaded or unloaded) at this node
Sets type of the node
Possible values: [dropoff, point, pickup, vehicle_position, depot]
Latest date and time when the node processing can be started. Usually equals close_time_ts and is applied to the dynamic algorithm type.
Name of the location.
Code of the location if applicable.
Date and time when this node is supposed to be visited. NOTE: This should be omitted unless required explicitly by the use case.
Dropoff node's close_time_ts_dynamic minus pickup node's open_time_ts_dynamicif algorithm is dynamic
Dropoff node's close_time_ts minus pickup node's open_time_ts otherwise
Date and time when node service started. Is required for vehicle.completed_nodes, otherwise may be omitted.
Flag that enables LIFO order check for nodes of this booking. Used only if use_lifo_order_check is set for model.
Enables or disables the LIFO order logic for this node, LIFO logic is a soft constraint forcing the pickups and drop offs to happen in LIFO sequence related to the vehicles (last picked up order is prioritized for the drop off)
falsePenalty value that defines that LIFO constraint for this node is soft.
A list of group names as strings for this node. Items in this list are used for processing the mutually-exclusive groups constraint.
maximum slack limitation for this node.
Transit stop weight. Weight of the node that is added to cost function if the stop is active.
Whether to allow the node to be re-assigned to another vehicle.
Rejection penalty for the node (a large value added to the overall cost function) for not performing this booking. If the value is null, the penalty value is taken from model_parameters.booking_penalty settings.
This value should be large enough to justify the cost of traveling to the node or the cost of violating soft constraints, if any, to have the node assigned to a vehicle. Values can vary from hundreds to millions depending on the use case.
Timestamp for which transits from this node should be calculated.
Default value is node.open_time_ts
Geofence id for this node.
List of geofence ids for this node (if node is close to geofences border).
Price of trip time for this booking. The overall trip cost for a booking is calculated as real travel time * trip_cost. The default value is defined in the scheduler settings.
Defines options to get the final scheduled time of this node. If set to 'max', the algorithm tries to "shift" a solution to schedule the node visit as late as possible within a given solution (thus minimizing slack); when set to 'min', it tries to schedule the node visit as early as possible. This is a post-processing step that does not impact the solution but tries to adjust the result.
Possible values: [min, max]
vehicle_characteristics object
Required vehicle characteristics to perform this node. Required vehicle characteristics for booking must be a dictionary mapping the required characteristic name to characteristic minimum value (as value convertible to integer) or value range (as dict, containing 'min' and 'max' keys).
Important note: all characteristics must be present in the list of characteristics for all vehicles.
property name* object
- number
- Ranged characteristic
- boolean
Value of the characteristic, for example:
{
"manpower": 3
}
Minimum value of the characteristic
Maximum value of the characteristic
Vehicle labels contain constraints, represented as dictionaries, that may contain string labels or sub-constraints. A constraint is a dictionary containing only one entry with keys: "and", "or", or "not". The keys "and" and "or" define the AND or OR logic functions, and their values should be a list of either string labels or dictionaries containing sub-constraints. The key "not" defines the NOT logic function, and its value can be a single string or a single sub-constraint.
Example of vehicle labels constraints:
'1' AND ('2' OR '3') AND NOT ('4' AND '5') as:
{"and": [{"or": ["2", "3"]}, {"not": {"and": ["4", "5"]}}]}
The end-of-vehicle-trip marker must be set for all nodes located at the depot(s). This allows the scheduler to calculate the number of vehicle trips and obey the number_of_trips constraint.
List of additional time windows.
completed_nodes object[]
A list of the nodes that have been completed by a vehicle. In case of having this data in the request, the optimization engine will assume that these nodes have been already completed by a vehicle. THis is required to respect cumulative constraints such as maximum travelled distance. This can be a result of previous calculations.
Unique identifier of the node
Required for pickup and dropoff nodes. Unique identifier of the booking this node belongs to (used to correlate pickup and dropoff nodes).
Transit stop corresponding to this node.
Latitude of the node
Longtitude of the node
demand objectrequired
The number of ordinary passengers to be transferred or a dictionary where the key is the type of seat (ordinary passenger is "passenger") and the value is the number of seats required.
In Logistics this could be how many tons of goods the vehicle need to pickup/dropoff from this node
Earliest date and time when the node processing can be started.
Latest date and time when the node processing can be started.
Time required for a vehicle to be serviced (loaded or unloaded) at this node
Sets type of the node
Possible values: [dropoff, point, pickup, vehicle_position, depot]
Latest date and time when the node processing can be started. Usually equals close_time_ts and is applied to the dynamic algorithm type.
Name of the location.
Code of the location if applicable.
Date and time when this node is supposed to be visited. NOTE: This should be omitted unless required explicitly by the use case.
Dropoff node's close_time_ts_dynamic minus pickup node's open_time_ts_dynamicif algorithm is dynamic
Dropoff node's close_time_ts minus pickup node's open_time_ts otherwise
Date and time when node service started. Is required for vehicle.completed_nodes, otherwise may be omitted.
Flag that enables LIFO order check for nodes of this booking. Used only if use_lifo_order_check is set for model.
Enables or disables the LIFO order logic for this node, LIFO logic is a soft constraint forcing the pickups and drop offs to happen in LIFO sequence related to the vehicles (last picked up order is prioritized for the drop off)
falsePenalty value that defines that LIFO constraint for this node is soft.
A list of group names as strings for this node. Items in this list are used for processing the mutually-exclusive groups constraint.
maximum slack limitation for this node.
Transit stop weight. Weight of the node that is added to cost function if the stop is active.
Whether to allow the node to be re-assigned to another vehicle.
Rejection penalty for the node (a large value added to the overall cost function) for not performing this booking. If the value is null, the penalty value is taken from model_parameters.booking_penalty settings.
This value should be large enough to justify the cost of traveling to the node or the cost of violating soft constraints, if any, to have the node assigned to a vehicle. Values can vary from hundreds to millions depending on the use case.
Timestamp for which transits from this node should be calculated.
Default value is node.open_time_ts
Geofence id for this node.
List of geofence ids for this node (if node is close to geofences border).
Price of trip time for this booking. The overall trip cost for a booking is calculated as real travel time * trip_cost. The default value is defined in the scheduler settings.
Defines options to get the final scheduled time of this node. If set to 'max', the algorithm tries to "shift" a solution to schedule the node visit as late as possible within a given solution (thus minimizing slack); when set to 'min', it tries to schedule the node visit as early as possible. This is a post-processing step that does not impact the solution but tries to adjust the result.
Possible values: [min, max]
vehicle_characteristics object
Required vehicle characteristics to perform this node. Required vehicle characteristics for booking must be a dictionary mapping the required characteristic name to characteristic minimum value (as value convertible to integer) or value range (as dict, containing 'min' and 'max' keys).
Important note: all characteristics must be present in the list of characteristics for all vehicles.
property name* object
- number
- Ranged characteristic
- boolean
Value of the characteristic, for example:
{
"manpower": 3
}
Minimum value of the characteristic
Maximum value of the characteristic
Vehicle labels contain constraints, represented as dictionaries, that may contain string labels or sub-constraints. A constraint is a dictionary containing only one entry with keys: "and", "or", or "not". The keys "and" and "or" define the AND or OR logic functions, and their values should be a list of either string labels or dictionaries containing sub-constraints. The key "not" defines the NOT logic function, and its value can be a single string or a single sub-constraint.
Example of vehicle labels constraints:
'1' AND ('2' OR '3') AND NOT ('4' AND '5') as:
{"and": [{"or": ["2", "3"]}, {"not": {"and": ["4", "5"]}}]}
The end-of-vehicle-trip marker must be set for all nodes located at the depot(s). This allows the scheduler to calculate the number of vehicle trips and obey the number_of_trips constraint.
List of additional time windows.
The list containing UIDs of nodes which represents the vehicle's partial route. The order in the list must represent the actual sequence of assigned nodes to the vehicle.
capacity objectrequired
Represents capacity constrains of the vehicle. This is a free form dictinoary with keys that must match with relevant demand values for nodes, otherwise the optimization will not be able to solve the VRP problem.
Timestamp of the vehicle operations start time.
Timestamp of the vehicle operations end time.
Vehicle cost factor.
Allowed duration of the vehicle break (i.e., driver break) in seconds. The break node is selected from one of the nodes in the path with the greatest slack. The break node cannot be the first or the last in the path. If slacks are identical, the break node is selected to be as close as possible to the middle of the path in prebook_cvrptw mode or to have minimal possible demand in prebook mode.
Minimum path duration when dynamic breaks are required. If real path duration is less than this value, then no dynamic break will be added.
"Break" is added only if the vehicle's path is longer than dynamic_break_min_path_duration. Setting dynamic_break_min_path_duration makes breaks always added. Break is not added if there is only one node in the path.
Maximum number of consecutive, non-identical drop-off locations after the last pickup location.
List of vehicle lables. Use to select approriate bookings for assignments based on rules defined in a node.vehicle_labels field.
If set to true, vehicle cost for this vehicle will not be added to objective value if the route for this vehicle contains only partial_route + partial_route_end
Maximum number of times a vehicle can return to the depot(s). Nodes located at a depot must be marked with end_of_trip=true.
In CVRPTW optimization mode (with all orders picked up at a single location/warehouse), this parameter is ignored since only one trip per vehicle is supported.
Max trip duration in seconds. New bookings are assigned to the vehicle as long as the total trip does not exceed this value. If the property max_trip_duration is not set explicitly, it is calculated as:
- for
dynamicalgorythm Dropoff node'sclose_time_ts_dynamicminus pickup node'sopen_time_ts_dynamic - in other cases Dropoff node's
close_time_tsminus pickup node'sopen_time_ts
efficiency vehicle_efficiency (object,null)
constraints object[]
This feature enables efficiency constraints for vehicles, managing how much capacity they utilize. It works by defining a list of constraints for various demand types. These constraints focus on two optional checks during a vehicle's trip:
Minimum Load: Ensures the vehicle is loaded with at least a specified minimum capacity throughout the trip. This promotes efficient vehicle usage. Maximum Remaining Load: Ensures the vehicle's remaining load at the end of a trip doesn't exceed a specified maximum. This discourages returns to the depot with significant unused capacity. Each check can be either strict or weak:
Strict: These constraints must be met. Failing a strict constraint is unacceptable, even if it means no solution is found. Weak: These constraints are preferred but not mandatory. If a weak constraint is violated, a penalty is added to the overall objective value. The penalty for violating a weak constraint is calculated as the sum of two components:
Fixed Penalty: A pre-defined penalty value. Linear Penalty: Calculated by multiplying the cost of over/under capacity by the amount of over/under capacity.
Demand name to apply the constraint.
This demand type must be present in at least one full booking.
If the demand set here is not present in any of the booking as a set demand type, the optimizer will fail the validation.
Minimum capacity after a series of consecutive pickups before dropoffs. If check is not strict then penalty is added to cost if capacity is less than minimum. If check is strict then route with too small capacity is invalid.
The same as loaded_min_capacity but represented as percentage.
Fixed penalty of undercapacity.
0Cost of undercapacity. The additional penalty is calculated as the product of undercapacity_cost and the undercapacity value.
0Flag indicates that check of undercapacity must be strict.
falseMaximum capacity after a series of consecutive dropoffs before pickups. If check is not strict then penalty is added to cost if capacity is greater than maximum. If check is strict then route with too large capacity is invalid.
Same as unloaded_max_capacity but represented as percentage.
Fixed penalty of overcapacity.
0Cost of overcapacity. The additional penalty is calculated as the product of overcapacity_cost and the overcapacity value.
0Flag, indicates, that check for overcapacity must be strict.
falseThe list containing uids of nodes which represents vehicle's partial route end.
Current vehicle's path as a sequence of (lat, lon) in encoded polyline format. Can be omitted unless required explicitly.
If defined, vehicle should stay at the same location until this time is reached.
Current date and time (vehicle's properties are valid this time). Can be normally omitted unless required explicitly for some retrospective or in the future calculations.
routing_engine object
Used only if mixed_fleet is set to true
Name of the engine to be used.
Possible values: [euclidian, euclidian_geo, asteria, graphhopper, mapbox, valhalla, osrm, osrme, google, here, spheroid, spheriodtd, tomtom]
asteriaRoad network to be used by the routing engine (routing profile)
osrmeAPI key for the mapping service
nullURL of the routing engine to request the data from
http://mapbox-osrm-proxySets approacch values in the resuts to unrestricted with false, and curb with true value. The approaches are set only for the first and the last stop in the trip
nullSets approacch values in the resuts to unrestricted with false, and curb with true value. The approaches are set for all waypoints in a trip except for the first and the last stop
nullApplies continue_straight flag to the routing request. WHen set to null default map setting is applied.
nullSpeed value used by the routing engine if fiexed speed is enabled with use_speed_in_routing flga
0Can be used to manually adjust the time needed to move between waypoints compared to what the routing engine provides based on the vehicle profile.
1trueDefines size of the matix to request from the routing engine with a single request for optimization purposes
250Defines default timestamp type to be used for requesting the route
start_timeIf enabled, forces the routing engine to use fixed speed and disregard speeds from the map
falseFlag that enables LIFO order check for this vehicle. Used only if use_lifo_order_check is set for the model.
falseThe number of physical stops (excluding depot, points, and vehicle_positions).
Ids of geofences, that are served by this vehicle or empty list means no restrictions.
Amortized vehicle cost (linear part). The amortized cost for a vehicle during optimization is calculated as L - QN^2, where L is the linear part of the amortized cost factor, Q is the quadratic part, and N is the number of nodes in the vehicle's path.
Amortized vehicle cost (quadratic part)
Identifier of the matrix. If omitted or null, the routing engine will be used to obtain the matrix.
Maximum trip length for this vehicle. Units are the same as the routing engine uses for distance calculation.
characteristics object
Vehicle characteristics. It must be a dictionary mapping a characteristic name to a characteristic value convertible to an integer. For every vehicle, all required characteristics (present in bookings or nodes) must be present.
property name* object
- number
- Ranged characteristic
- boolean
Value of the characteristic, for example:
{
"manpower": 3
}
Minimum value of the characteristic
Maximum value of the characteristic
Minimum time when a dynamic break can start.
The time window for a break is set using the dynamic_break_start_time and dynamic_break_end_time fields. These fields define the time interval when a break can occur. Setting only one of these parameters (a half-window) is also a valid configuration. In this case, only the minimum or maximum time will be checked.
Maximum time when dynamic break should end.
Average time between breaks in seconds.
When dynamic_break_avg_time_between_breaks is not set, single break mode is used. In single break mode, there is only zero or one break per path. Dynamic breaks are modeled as some amount of time after servicing one of the nodes in the path. For every vehicle, there can be only zero or one dynamic break. Break duration sets the amount of "free" time on the break node. When dynamic_break_duration is set to zero, breaks will not be added to any nodes for this vehicle.
If dynamic_break_avg_time_between_breaks is set to a non-zero value, then multiple breaks mode is used. In multiple breaks mode, there might be zero or more breaks per path. The dynamic_break_avg_time_between_breaks parameter sets the amount of time between the end of the previous break and the start of the next break. The dynamic_break_max_latency parameter sets the maximum amount of time the break can be late. There might be only one dynamic break per transit (between two nodes).
This value specifies the maximum allowable delay (lateness) for the break.
Maximum number of consecutive, non-identical pickup locations after the last drop-off location.
Each string represents a node.uid. When engine_settings.solver_parameters.first_solution_strategy is set to EVALUATOR_STRATEGY, these lists assign the first solution route for the vehicles.
{
"agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"lat": 0,
"lon": 0,
"assigned_nodes": [
{
"uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"booking_uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"stop_id": "string",
"lat": 0,
"lon": 0,
"demand": {},
"open_time_ts": "2024-07-29T15:51:28.071Z",
"close_time_ts": "2024-07-29T15:51:28.071Z",
"service_time": 0,
"node_type": "dropoff",
"close_time_ts_dynamic": "2024-07-29T15:51:28.071Z",
"location_name": "string",
"location_code": "string",
"scheduled_ts": "2024-07-29T15:51:28.071Z",
"max_trip_duration": 0,
"started_service_at_ts": "2024-07-29T15:51:28.071Z",
"lifo_order_check": false,
"lifo_order_penalty": 0,
"groups": [
"string"
],
"max_slack": 0,
"weight": 0,
"allow_jump": true,
"penalty": 0,
"matrix_timestamp": "2024-07-29T15:51:28.071Z",
"geofence_id": "string",
"geofence_ids": [
"string"
],
"trip_cost": 0,
"finalization_type": "min",
"vehicle_characteristics": {},
"vehicle_labels": "Unknown Type: object,null",
"end_of_trip": true,
"time_windows": [
"string"
]
}
],
"completed_nodes": [
{
"uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"booking_uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"stop_id": "string",
"lat": 0,
"lon": 0,
"demand": {},
"open_time_ts": "2024-07-29T15:51:28.071Z",
"close_time_ts": "2024-07-29T15:51:28.071Z",
"service_time": 0,
"node_type": "dropoff",
"close_time_ts_dynamic": "2024-07-29T15:51:28.071Z",
"location_name": "string",
"location_code": "string",
"scheduled_ts": "2024-07-29T15:51:28.071Z",
"max_trip_duration": 0,
"started_service_at_ts": "2024-07-29T15:51:28.071Z",
"lifo_order_check": false,
"lifo_order_penalty": 0,
"groups": [
"string"
],
"max_slack": 0,
"weight": 0,
"allow_jump": true,
"penalty": 0,
"matrix_timestamp": "2024-07-29T15:51:28.071Z",
"geofence_id": "string",
"geofence_ids": [
"string"
],
"trip_cost": 0,
"finalization_type": "min",
"vehicle_characteristics": {},
"vehicle_labels": "Unknown Type: object,null",
"end_of_trip": true,
"time_windows": [
"string"
]
}
],
"partial_route": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"capacity": {},
"start_time": "string",
"end_time": "string",
"vehicle_cost": 0,
"dynamic_break_duration": 0,
"dynamic_break_min_path_duration": 0,
"max_dropoff_locations": 0,
"labels": "Unknown Type: array,null",
"zero_cost_if_only_partial_routes": true,
"number_of_trips": 0,
"max_trip_duration": 0,
"efficiency": "Unknown Type: object,null",
"partial_route_end": "string",
"path": "string",
"should_wait_until": "2024-07-29T15:51:28.071Z",
"current_time": "string",
"routing_engine": {
"routing_engine_name": "asteria",
"road_network": "osrme",
"key": null,
"url": "http://mapbox-osrm-proxy",
"curb": null,
"intermediate_curb": null,
"continue_straight": null,
"speed": 0,
"time_factor": 1,
"make_depot_zero": true,
"batch_matrix_size": 250,
"osrme_timestamp_mode": "start_time",
"use_speed_in_routing": false
},
"lifo_order_check": false,
"max_physical_stops": 0,
"geofence_ids": [
0
],
"amortized_linear_cost_factor": 0,
"amortized_quadratic_cost_factor": 0,
"matrix_id": "string",
"max_trip_length": 0,
"characteristics": {},
"dynamic_break_start_time": "2024-07-29T15:51:28.071Z",
"dynamic_break_end_time": "2024-07-29T15:51:28.071Z",
"dynamic_break_avg_time_between_breaks": 0,
"dynamic_break_max_latency": 0,
"max_pickup_locations": 0,
"first_solution": [
"string"
]
}