はじめに (Introduction)
問題空間 (Problem space)
Stateless API は、VRPPDTW および CVRPTW 問題を解決する機能を提供します。
いつ使用すべきか (When it should be used)
Stateless API は、SWAT が開発した最適化エンジンへの直接アクセスを提供します。それは高い複雑さを持ちながら、同時にユースケースに適用可能なビジ ネスルールを設定する柔軟性を提供します。
Stateless アプローチでは、SWAT バックエンドはコンシューマーによって送信されたオブジェクトの状態を維持しません。これは、コンシューマーが持つデータ主権やデータプライバシーに関する懸念に対処する可能性がありますが、コンシューマーがコンシューマーアプリケーション内のオブジェクトとマスターデータの状態を維持するという追加の負担を生み出します。さらに、SWAT バックエンドにデータが永続化されないため、Stateless API は、Driver アプリケーションや Web アプリケーションなどの SWAT アプリケーションとの統合には使用できません。
Stateless API では、すべてのペイロードに、車両の位置、ドロップオフとピックポイント、最適化セッション、予約など、最適化を実行するために必要なすべてのデータを含める必要があります。
一般的に、複雑さとエンドカスタマーへのサポートを提供するコンシューマーへの追加負担のため、コンシューマーアプリケーションで Stateless API を使用することはお勧め しません。Stateless API を使用する開発者は、VRP 空間についてよく理解していることが期待されます。
入力と出力 (Inputs and outputs)
Stateless API リクエストには、計算に必要なすべてのデータを含める必要があります。出力には、ノードから車両への割り当て、割り当てられた予約のリス ト、および制約を満たさないか利用可能な容量がないために割り当てられない予約のリストが含まれます。
同期および非同期モード (Synchronous and asynchronous modes)
Stateless API は、同期および非同期 の両方の動作モードを提供します。最適化の実行には、ノードと予約の量によっては時間がかかる場合があり、solver_parameters.time_limit_ms 設定 によって制限されます。同期モードでは、結果はリクエストへのレスポンスですぐに利用可能になりますが、非同期モードでは、job_id を使用したコールバックを通じて結果が利用可能になります。async モードでの最適化の結果を取得するには、API 仕様 を参照してください。sync モードでは、結果は最適化リクエストへのレスポンスですぐに利用可能になります。
計算時間の最大制限は、VRP 問題の複雑さ（サイズ、制約の数）、初期解戦略のタイプ、およびローカル検索演算子の構成に基づいて設定できます。
サポートされているスケジューリングモード (Supported scheduling modes)
Stateless API は2つのモードをサポートしています：CVRPTW 問題を解決するために使用される prebook_cvrptw モード、または VRPPDTW 問題を解決するための prebook モードです。
CVRPTW モードは、ピックアップポイント/DC/倉庫が1つだけあるシナリオにのみ適しています。このモードでは、すべてのピックアップノードが結合され、ノードの数が大幅に削減され、結果が大幅に改善されます。ピックアップノードが結合されているため、各車両は最大1回のトリップ（または1回のピックアップ）に制限されます。このモードは、1回のピックアップと1回のドロップオフの両方のケース（つまり、単一の DC\倉庫からの商品の配送、および複数のピックアップ場所から単一の DC\倉庫への商品の収集）をサポートしています。
リクエスト例 (Example requests)
単一の車両を使用した VRPPDTW モデルの例を以下に示します。各ピックアップノードには正の需要値（例では units: 10）があり、ドロップオフノードには負の需要値（例では units: -10）があることに注意してください。ドロップオフポイントとピックアップポイントの各ペアは、ペア 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
}
]
}
同様の問題の例ですが、CVRPTW 問題の場合を以下に示します。ピックアップノード（車両の位置と同じ）が1つあり、車両はピックアップ場所から開始していることに注意してください。この場合、ピックアップノードの需要は0であり 、各ドロップオフポイントの需要は正の値です。この場合、各予約はドロップオフポイントごとに一意であり、車両は partial_route 配列内のピックアップノードの uid を使用して、開始位置としてピックアップに接続されます。
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
}
]
}