Introduction
Problem space
Stateless API provides capabilities to solve VRPPDTW and CVRPTW problems.
When it should be used
Stateless API provides direct access to the optimization engine developed by SWAT. It has high complexity at the same time offering flexibility in setting up business rules applicable to your use case.
With Stateless approach, SWAT backend is not maintaining state of objects submitted by the consumer which may address concerns that the consumer has about data sovereignty or data privacy, however it creates additional burden for a consumer to maintain the state of objects and master data in the consuming application. In additions, since there is no data persisted in SWAT backend, STateless API can not be used for integration with SWAT applications such as Driver application or web applications.
With Stateless API, every payload has to include all data required to execute optimization such as vehicle locations, drop off and pick points, optimization sessions, bookings.
Generally, we do not recommend using Stateless API in consuming applications due to complexity and additional burden for a consumer to provide support for the end customers. It is expected that the developers using Stateless API have good understanding of the VRP space.
Inputs and outputs
Stateless API request has to contain all the data requires for calculations. Output contains node-to-vehicle assignments, a list of assigned bookings and a list of bookings that can not be assigned due to not meeting constraints or available capacity.
Synchronous and asynchronous modes
Stateless API provides both synchronous and asynchronous operating modes. Optimization run can take some time depending on the amount of nodes and bookings, and is limited by solver_parameters.time_limit_ms setting. In synchronous mode, the result will be available immediately in the response to the request, while in asynchronous mode the result will be available through a callback using job_id. Please refer to API specification to retrieve the results of optimization in async mode. In sync mode the results will be available immediately in the response to the optimization request.
Maximum limit of calculation time can be set based on the complexity of the VRP problem (size, number of constraints), type of first solution strategy, and configuration of local search operators.
Supported scheduling modes
Stateless API supports two modes: prebook_cvrptw mode that is used to solve CVRPTW problems or prebook mode to solve VRPPDTW problems.
CVRPTW mode is only suitable for scenarios with only one pickup point/DC/warehouse. In this mode, all the pickup nodes are combined together, significantly reducing the number of nodes, which significantly improve the result. Each vehicle is limit to the maximum of one trip (or one pickup), as pickup nodes are combined. The mode supports both one pickup and one drop off cases (i.e. distribution of goods from a single DC\warehouse, as well as collection of goods from multiple pickup locations to a single DC\warehouse)
Example requests
Example of VRPPDTW model with a single vehicle is below. Please note that each pickup node has positive demand value (in the example units: 10) and dropoff nodes have negative demand value (in the example units: -10). Each pair of dropoff and pickup points are linked with each by having the same unique for a pair booking_uid.
See JSON payload
{
"current_time": "2024-07-10T08:00:00+00:00",
"engine_settings": {
"calculation_parameters": {
"calculations_mode": "sync",
"scheduling_mode": "prebook"
},
"model_parameters": {
"mixed_fleet": false,
"optimize_quantity": "total_time",
},
"routing_engine": {
"batch_matrix_size": 250,
"continue_straight": true,
"curb": false,
"key": "<routing_key>",
"make_depot_zero": true,
"road_network": "van",
"routing_engine_name": "osrme",
"speed": null,
"time_factor": 1,
"url": "http://mapbox-osrm-proxy",
"use_speed_in_routing": false
},
"solver_parameters": {}
},
"nodes": [
{
"booking_uid": "b00c0000-2024-0421-0616-000000000001",
"close_time_ts": "2026-01-02T00:35:00+00:00",
"close_time_ts_dynamic": "2026-01-02T00:35:00+00:00",
"demand": {
"units": 10
},
"end_of_trip": null,
"geofence_ids": [],
"lat": 1.290662,
"lon": 103.942707,
"lifo_order_check": false,
"lifo_order_penalty": null,
"location_name": "Pickup location 1",
"matrix_timestamp": "2024-07-10T08:00:00+00:00",
"max_slack": null,
"node_type": "pickup",
"open_time_ts": "2026-01-01T00:30:00+00:00",
"service_time": 0.0,
"trip_cost": 0.0,
"uid": "f0de0000-2024-0731-88ad-05ddd46ce71d",
"vehicle_characteristics": {}
},
{
"booking_uid": "b00c0000-2024-0421-0616-000000000001",
"close_time_ts": "2026-01-03T09:00:00+00:00",
"close_time_ts_dynamic": "2026-01-03T09:00:00+00:00",
"demand": {
"units": -10
},
"end_of_trip": null,
"geofence_ids": [],
"lat": 1.280097,
"lon": 103.889129,
"lifo_order_check": false,
"lifo_order_penalty": null,
"location_name": "Dropoff location 1",
"matrix_timestamp": "2024-07-10T08:00:00+00:00",
"max_slack": null,
"node_type": "dropoff",
"open_time_ts": "2026-01-01T00:00:00+00:00",
"service_time": 360.0,
"trip_cost": 0.0,
"uid": "f0de0001-2024-0731-88ad-05ddd46ce72d",
"vehicle_characteristics": {}
},
{
"booking_uid": "b00c0000-2024-0421-0616-000000000002",
"close_time_ts": "2026-01-02T00:35:00+00:00",
"close_time_ts_dynamic": "2026-01-02T00:35:00+00:00",
"demand": {
"units": 10
},
"end_of_trip": null,
"geofence_ids": [],
"lat": 1.290862,
"lon": 103.952507,
"lifo_order_check": false,
"lifo_order_penalty": null,
"location_name": "Pickup location 2",
"matrix_timestamp": "2024-07-10T08:00:00+00:00",
"max_slack": null,
"node_type": "pickup",
"open_time_ts": "2026-01-01T00:30:00+00:00",
"service_time": 0.0,
"trip_cost": 0.0,
"uid": "f0de0000-2024-0731-88ad-05ddd46ce73d",
"vehicle_characteristics": {}
},
{
"booking_uid": "b00c0000-2024-0421-0616-000000000002",
"close_time_ts": "2026-01-03T09:00:00+00:00",
"close_time_ts_dynamic": "2026-01-03T09:00:00+00:00",
"demand": {
"units": -10
},
"end_of_trip": null,
"geofence_ids": [],
"lat": 1.290097,
"lon": 103.989129,
"lifo_order_check": false,
"lifo_order_penalty": null,
"location_name": "Dropoff location 2",
"matrix_timestamp": "2024-07-10T08:00:00+00:00",
"max_slack": null,
"node_type": "dropoff",
"open_time_ts": "2026-01-01T00:00:00+00:00",
"service_time": 360.0,
"trip_cost": 0.0,
"uid": "f0de0001-2024-0731-88ad-05ddd46ce74d",
"vehicle_characteristics": {}
}
],
"vehicles": [
{
"agent_id": "dc1e0000-2024-0731-b23d-5206f1c21d09",
"capacity": {
"units": 999
},
"characteristics": {},
"completed_nodes": [],
"end_time": "2026-01-05T14:59:59+00:00",
"lat": 1.292097,
"lon": 103.999129,
"routing_engine": {
"batch_matrix_size": 250,
"curb": false,
"key": "<routing_key>",
"make_depot_zero": true,
"road_network": "van",
"routing_engine_name": "osrme",
"speed": null,
"time_factor": 1,
"url": "http://mapbox-osrm-proxy",
"use_speed_in_routing": false
},
"service_number": "Van 2 - instance",
"start_time": "2026-01-01T00:00:00+00:00",
"vehicle_cost": 1000.0
}
]
}
An example of a similar problem but for a CVRPTW problem is below. Please note, there is one pickup node (which is the same as vehicle location), and the vehicle is starting from the pickup location. Demand in this case is 0 for the pickup node, and a positive value for each dropoff point. Each booking in this case is unique for a drop off point, and vehicle is attached to the pickup as a starting location by using uid of the pickup node in a partial_route array for a vehicle.
See JSON payload
{
"current_time": "2024-07-10T08:00:00+00:00",
"engine_settings": {
"calculation_parameters": {
"calculations_mode": "sync",
"scheduling_mode": "prebook_cvrptw"
},
"model_parameters": {
"mixed_fleet": false,
"optimize_quantity": "total_time",
"groups_order": {}
},
"routing_engine": {
"batch_matrix_size": 250,
"continue_straight": true,
"curb": false,
"key": "<routing_key>",
"make_depot_zero": true,
"road_network": "van",
"routing_engine_name": "osrme",
"speed": null,
"time_factor": 1,
"url": "http://mapbox-osrm-proxy",
"use_speed_in_routing": false
},
"solver_parameters": {}
},
"nodes": [
{
"booking_uid": "b00c0000-2024-0421-0616-000000000001",
"close_time_ts": "2026-01-03T09:00:00+00:00",
"close_time_ts_dynamic": "2026-01-03T09:00:00+00:00",
"demand": {
"units": 10
},
"end_of_trip": false,
"geofence_ids": [],
"lat": 1.280097,
"lon": 103.889129,
"lifo_order_check": false,
"lifo_order_penalty": null,
"location_name": "Dropoff location 1",
"matrix_timestamp": "2024-07-10T08:00:00+00:00",
"max_slack": null,
"node_type": "dropoff",
"open_time_ts": "2026-01-01T00:00:00+00:00",
"service_time": 360.0,
"trip_cost": 0.0,
"uid": "f0de0001-2024-0731-88ad-05ddd46ce72d",
"vehicle_characteristics": {}
},
{
"booking_uid": "b00c0000-2024-0421-0616-000000000002",
"close_time_ts": "2026-01-03T09:00:00+00:00",
"close_time_ts_dynamic": "2026-01-03T09:00:00+00:00",
"demand": {
"units": 10
},
"end_of_trip": false,
"geofence_ids": [],
"lat": 1.290097,
"lon": 103.989129,
"lifo_order_check": false,
"lifo_order_penalty": null,
"location_name": "Dropoff location 2",
"matrix_timestamp": "2024-07-10T08:00:00+00:00",
"max_slack": null,
"node_type": "dropoff",
"open_time_ts": "2026-01-01T00:00:00+00:00",
"service_time": 360.0,
"trip_cost": 0.0,
"uid": "f0de0001-2024-0731-88ad-05ddd46ce74d",
"vehicle_characteristics": {}
},
{
"close_time_ts": "2026-01-05T00:35:00+00:00",
"close_time_ts_dynamic": "2026-01-05T00:35:00+00:00",
"demand": {
"units": 0
},
"lat": 1.290662,
"lon": 103.943407,
"location_name": "Office",
"max_trip_duration": 0,
"node_type": "point",
"open_time_ts": "2026-01-01T00:00:00+00:00",
"end_of_trip": true,
"service_time": 0.0,
"trip_cost": 0,
"weight": 0.0,
"uid": "dc1e0000-2024-0731-b23d-5206f1c21d09"
}
],
"vehicles": [
{
"agent_id": "dc1e0000-2024-0731-aaaa-5206f1c21d09",
"capacity": {
"units": 999
},
"characteristics": {},
"partial_route": ["dc1e0000-2024-0731-b23d-5206f1c21d09"],
"completed_nodes": [],
"end_time": "2026-01-10T14:59:59+00:00",
"lat": 1.290662,
"lon": 103.943407,
"routing_engine": {
"batch_matrix_size": 250,
"curb": false,
"key": "<routing_key>",
"make_depot_zero": true,
"road_network": "van",
"routing_engine_name": "osrme",
"speed": null,
"time_factor": 1,
"url": "http://mapbox-osrm-proxy",
"use_speed_in_routing": false
},
"service_number": "Van 2 - instance",
"start_time": "2024-01-01T00:00:00+00:00",
"vehicle_cost": 1000.0
}
]
}