Vehicle data model used in optimization API

agent_idstring<uuid>required

Represents and validates UUID string

latnumberrequired

Current latitude of the vehicle

lonnumberrequired

Current longitude of the vehicle

assigned_nodes object[]

A list of the nodes that have been assigned to a vehicle. In case of having this data in the request, the optimization engine will assume that these nodes have been already assigned to a vehicle. This can be an outcome of previous calculations.

Array [

uidstring<uuid>required

Unique identifier of the node

booking_uidstring<uuid>

Required for pickup and dropoff nodes. Unique identifier of the booking this node belongs to (used to correlate pickup and dropoff nodes).

stop_idstring

Transit stop corresponding to this node.

latnumberrequired

Latitude of the node

lonnumberrequired

Longitude 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 needs to pickup/dropoff from this node

property name*integer

open_time_tsstring<date-time>required

Earliest date and time when the node processing can be started.

close_time_tsstring<date-time>required

Latest date and time when the node processing can be started.

service_timenumberrequired

Time required for a vehicle to be serviced (loaded or unloaded) at this node

node_typeNode types enum (string)required

Sets type of the node

Possible values: [dropoff, point, pickup, vehicle_position, depot]

close_time_ts_dynamicstring<date-time>

Latest date and time when the node processing can be started. Usually equals close_time_ts and is applied to the dynamic algorithm type.

location_namestring

Name of the location.

location_codestring

Code of the location if applicable.

scheduled_tsstring<date-time>

Date and time when this node is supposed to be visited. NOTE: This should be omitted unless required explicitly by the use case.

max_trip_durationnumber | nullnullable

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

started_service_at_tsstring,null<date-time>nullable

Date and time when node service started. Is required for vehicle.completed_nodes, otherwise may be omitted.

lifo_order_checkboolean

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)

Default value: false

lifo_order_penaltynumber | nullnullable

Penalty value that defines that LIFO constraint for this node is soft.

groupsstring[]

list of group names as strings for this node. Items in this list are used for processing of mutually-exclusive groups constraint.

max_slacknumber | nullnullable

maximum slack limitation for this node.

weightnumber | nullnullable

Transit stop weight. Weight of the node that is added to cost function if the stop is active.

allow_jumpboolean

Whether to allow the node to be re-assigned to another vehicle.

penaltynumber | nullnullable

Rejection penalty for the node (large value added to overall cost function) for not performing this booking. If value is null penalty value is taken from model_parameters.booking_penalty settings. This value should be large enough to justify cost of travelling to the node, or 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 usecase.

matrix_timestampstring,null<date-time>nullable

Timestamp for which transits from this node should be calculated. Default value is node.open_time_ts

geofence_idstring | nullnullable

Geofence id for this node.

geofence_idsstring[]

List of geofence ids for this node (if node is close to geofences border).

trip_costnumber<float>

Price of trip time for this booking. Overall trip cost for booking is calculated as real travel time * trip_cost. Default value is defined in scheduler settings.

finalization_typestring

Defined options to get the final scheduled time of this node. If set to 'max', the algorithm is trying to "shift" a solution to schedule a 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

anyOf

number

number

Value of the characteristic, for example:

{
    "manpower": 3
}

Ranged characteristic

minnumber

Minimum value of the characteristic

maxnumber

Maximum value of the characteristic

vehicle_labelsobject | nullnullable

Vehicle labels contain constraints, represented as dicts, that may contain string labels or sub-constraints. A constraint is a dict, containing only one entry with keys: "and", "or" or "not". Keys "and" and "or" define the AND or OR logic functions. Values for these keys should be a list of either string labels or dicts, containing sub-constraints. The key "not" defines the NOT logic function. The value for this key 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"]}}]}

end_of_tripboolean | nullnullable

End of vehicle trip marker must be set for all nodes located at the depot(s). This allows scheduler to calculate number of vehicle trips and obey number_of_trips constraint.

time_windowsstring[]

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.

Array [

uidstring<uuid>required

Unique identifier of the node

booking_uidstring<uuid>

Required for pickup and dropoff nodes. Unique identifier of the booking this node belongs to (used to correlate pickup and dropoff nodes).

stop_idstring

Transit stop corresponding to this node.

latnumberrequired

Latitude of the node

lonnumberrequired

Longitude 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 needs to pickup/dropoff from this node

property name*integer

open_time_tsstring<date-time>required

Earliest date and time when the node processing can be started.

close_time_tsstring<date-time>required

Latest date and time when the node processing can be started.

service_timenumberrequired

Time required for a vehicle to be serviced (loaded or unloaded) at this node

node_typeNode types enum (string)required

Sets type of the node

Possible values: [dropoff, point, pickup, vehicle_position, depot]

close_time_ts_dynamicstring<date-time>

Latest date and time when the node processing can be started. Usually equals close_time_ts and is applied to the dynamic algorithm type.

location_namestring

Name of the location.

location_codestring

Code of the location if applicable.

scheduled_tsstring<date-time>

Date and time when this node is supposed to be visited. NOTE: This should be omitted unless required explicitly by the use case.

max_trip_durationnumber | nullnullable

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

started_service_at_tsstring,null<date-time>nullable

Date and time when node service started. Is required for vehicle.completed_nodes, otherwise may be omitted.

lifo_order_checkboolean

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)

Default value: false

lifo_order_penaltynumber | nullnullable

Penalty value that defines that LIFO constraint for this node is soft.

groupsstring[]

list of group names as strings for this node. Items in this list are used for processing of mutually-exclusive groups constraint.

max_slacknumber | nullnullable

maximum slack limitation for this node.

weightnumber | nullnullable

Transit stop weight. Weight of the node that is added to cost function if the stop is active.

allow_jumpboolean

Whether to allow the node to be re-assigned to another vehicle.

penaltynumber | nullnullable

Rejection penalty for the node (large value added to overall cost function) for not performing this booking. If value is null penalty value is taken from model_parameters.booking_penalty settings. This value should be large enough to justify cost of travelling to the node, or 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 usecase.

matrix_timestampstring,null<date-time>nullable

Timestamp for which transits from this node should be calculated. Default value is node.open_time_ts

geofence_idstring | nullnullable

Geofence id for this node.

geofence_idsstring[]

List of geofence ids for this node (if node is close to geofences border).

trip_costnumber<float>

Price of trip time for this booking. Overall trip cost for booking is calculated as real travel time * trip_cost. Default value is defined in scheduler settings.

finalization_typestring

Defined options to get the final scheduled time of this node. If set to 'max', the algorithm is trying to "shift" a solution to schedule a 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

anyOf

number

number

Value of the characteristic, for example:

{
    "manpower": 3
}

Ranged characteristic

minnumber

Minimum value of the characteristic

maxnumber

Maximum value of the characteristic

vehicle_labelsobject | nullnullable

Vehicle labels contain constraints, represented as dicts, that may contain string labels or sub-constraints. A constraint is a dict, containing only one entry with keys: "and", "or" or "not". Keys "and" and "or" define the AND or OR logic functions. Values for these keys should be a list of either string labels or dicts, containing sub-constraints. The key "not" defines the NOT logic function. The value for this key 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"]}}]}

end_of_tripboolean | nullnullable

End of vehicle trip marker must be set for all nodes located at the depot(s). This allows scheduler to calculate number of vehicle trips and obey number_of_trips constraint.

time_windowsstring[]

List of additional time windows.

]

partial_routestring<uuid>[]

The list containing uids of nodes which represents vehicle's partial route. The order in the list must represent the actual sequence of assigned nodes to thte vehicle.

capacity objectrequired

Represents capacity constraints of the vehicle. This is a free-form dictionary with keys that must match with relevant demand values for nodes; otherwise, the optimization will not be able to solve the VRP problem.

property name*integer

start_timestring | nullnullable

Timestamp of the vehicle operations start time.

end_timestring | nullnullable

Timestamp of the vehicle operations end time.

vehicle_costinteger

Vehicle cost factor

dynamic_break_durationinteger | nullnullable

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.

dynamic_break_min_path_durationinteger | nullnullable

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.

max_dropoff_locationsnumber | nullnullable

Maximum number of consecutive non-identical dropoff locations after last pickup location.

labelsstring[]nullable

List of vehicle labels. Use to select appropriate bookings for assignments based on rules defined in a node.vehicle_labels field.

zero_cost_if_only_partial_routesboolean

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

number_of_tripsinteger | nullnullable

Maximum number of times a vehicle can return to the depot(s). Nodes located at the 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_durationinteger | nullnullable

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 dynamic algorithm: Dropoff node's close_time_ts_dynamic minus pickup node's open_time_ts_dynamic
• in other cases: Dropoff node's close_time_ts minus pickup node's open_time_ts

efficiency Vehicle efficiency constraiont (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.

Array [

demand_namestring

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.

loaded_min_capacitynumber | nullnullable

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.

loaded_min_capacity_percentagenumber | nullnullable

The same as loaded_min_capacity but represented as percentage.

loaded_undercapacity_penaltyinteger

Fixed penalty of undercapacity.

Default value: 0

loaded_undercapacity_costinteger

Cost of undercapacity. Additional penalty is calculated as prooduct of undercapacity_cost and undercapacity value.

Default value: 0

loaded_undercapacity_check_strictboolean

Flag indicates that check of undercapacity must be strict.

Default value: false

unloaded_max_capacitynumber | nullnullable

Maximum 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.

unloaded_max_capacity_percentagenumber | nullnullable

Same as unloaded_max_capacity but represented as percentage.

unloaded_overcapacity_penaltyinteger

Fixed penalty of overcapacity.

Default value: 0

unloaded_overcapacity_costinteger

Cost of overcapacity. The additional penalty is calculated as product of overcapacity_cost and overcapacity value.

Default value: 0

unloaded_overcapacity_check_strictboolean

Flag, indicates, that check for overcapacity must be strict.

Default value: false

]

partial_route_endstring[]

The list containing uids of nodes which represents vehicle's partial route end.

pathstring

Current vehicle's path as a sequence of (lat,lon) in encoded polyline format. Can be normally omitted unless required explicitly.

should_wait_untilstring,null<date-time>nullable

If defined, vehicle should stay at the same location until this time is reached.

current_timestring

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

routing_engine_namestring

Name of the engine to be used.

Possible values: [euclidian, euclidian_geo, asteria, graphhopper, mapbox, valhalla, osrm, osrme, google, here, spheroid, spheriodtd, tomtom]

Default value: asteria

road_networkstring

Road network to be used by the routing engine

Default value: combi

speednumber | nullnullable

Speed value used by the routing engine

Default value: 0

time_factornumber

Can be used to manually adjust time needed to move between the waypoints compared to what the routing engine provides based on behicle profile.

Default value: 1

make_depot_zeroboolean

Default value: true

lifo_order_checkboolean

flag that enables LIFO order check for this vehicle. Used only if use_lifo_order_check is set for model.

Default value: false

max_physical_stopsinteger | nullnullable

The number of physical stops (except depot, points, vehicle_positions)

geofence_idsinteger[]

Ids of geofences, that are served by this vehicle or empty list means no restrictions.

amortized_linear_cost_factorinteger | nullnullable

Amortized vehicle cost (linear part) The amortized cost for a vehicle during optimization is calculated as L - QN^2, where Lis a linear part of the amortized cost factor, Q quadratic part of the amortized cost factor, N number of nodes in the vehicle's path.

amortized_quadratic_cost_factorinteger | nullnullable

Amortized vehicle cost (quadratic part)

matrix_idstring

identifier of matrix. If omitted or null routing engine will be used to obtain matrix

max_trip_lengthnumber,null<float>nullable

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 characteristic name to characteristic value convertible to integer. For every vehicle all required (present in bookings or nodes) characteristics should be present.

property name* object

anyOf

number

number

Value of the characteristic, for example:

{
    "manpower": 3
}

Ranged characteristic

minnumber

Minimum value of the characteristic

maxnumber

Maximum value of the characteristic

dynamic_break_start_timestring,null<date-time>nullable

Minimum time when dynamic break can start. The time window for a break is set using dynamic_break_start_time and dynamic_break_end_time fields. These fields define the time interval when a break can happen. Setting only one of these parameters (half-window) is also a valid configuration. In this case, only the minimum or maximum time will be checked.

dynamic_break_end_timestring,null<date-time>nullable

Maximum time when dynamic break should end.

dynamic_break_avg_time_between_breaksinteger

Average time between breaks in seconds. When the 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 modelled 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 nonzero value, then multiple breaks mode is used. In multiple breaks mode, there might be zero or more breaks per path. Parameter dynamic_break_avg_time_between_breaks sets amount of time between end of previous break and start of next break. Parameter dynamic_break_max_latency sets maximum amount of time the break can be late. There might be only one dynamic break per transit (between two nodes).

dynamic_break_max_latencyinteger

This value specifies the maximum allowable delay (lateness) for the break.

max_pickup_locationsinteger | nullnullable

Maximum number of consecutive non-identical pickup locations after last dropoff location.

first_solutionstring[]

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.

logistics_optimize_slackboolean

If set true, the solver will apply additional penalty to slack in order to reduce it. Should be used only in combination with model_parameters.path_constraints_mode": "logistics" otherwise the parameter is ignored

Default value: false

Vehicle data model used in optimization API

{
  "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": "combi",
    "speed": 0,
    "time_factor": 1,
    "make_depot_zero": true
  },
  "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"
  ],
  "logistics_optimize_slack": false
}