Route Optimization API の目的は、車両フリートが一連の場所を訪問するルートを計画することです。OptimizeToursRequest オブジェクトは、これらの車両と場所のプロパティを記述するもので、すべてのエンドポイントのリクエスト本文の主要な構造です。
OptimizeToursRequest オブジェクトの基本構造は次のとおりです。
modelフィールドには、次の 2 つのキーフィールドを含むShipmentModelメッセージが格納されます。
このドキュメントでは、次のメッセージ タイプについて説明します。
ShipmentModel: 配送、利用可能な車両、それらの関係を記述するその他のオブジェクトのリストを保持します。Shipment: 車両が訪問する場所を記述します。集荷と配達の実際の荷物や、車両のドライバーがサービスを提供する場所を表すことができます。Vehicle: 配送場所間の輸送手段を記述します。各車両は、実際の車両または徒歩で移動する人に相当します。
ShipmentModel
ShipmentModel には、ルート最適化問題の要素が格納されます。これには、一連の車両で実行される一連の配送が含まれます。その際、制約を考慮し、全体的な費用を最小限に抑えます。
次の表に、ShipmentModel の関連プロパティを示します。
| プロパティ | 説明 |
|---|---|
shipments、vehicles |
1 つまたは複数の配送と車両の詳細を含む必須オブジェクト。 |
globalStartTime、globalEndTime |
すべての車両がすべての配送を完了する必要がある時間枠の開始と終了を示します。これらのプロパティは必須ではありませんが、オプティマイザーは時間制約を遵守すると最も効果的に機能するため、含めることをおすすめします。 |
ShipmentModel のプロパティの完全なリストについては、リファレンス ドキュメントをご覧ください。
ShipmentModel の例
この例では、犬のデイケア サービスを運営しており、リクエストの作成を開始しています。配送と車両は後で定義しますが、まずは営業時間と 1 時間あたりの運用コストを設定します。
この例では、リクエストの ShipmentModel プロパティ値は次のとおりです。
| プロパティ | 値 | 説明 |
|---|---|---|
globalStartTime |
2024-02-13T00:00:00.000Z | 営業時間の開始日時。 |
globalEndTime |
2024-02-14T06:00:00.000Z | 営業時間の終了日時。 |
以下は、サンプル シナリオの値を組み込んだ ShipmentModel メッセージのコードサンプルです。
{ "model": { "shipments": [ ... ], "vehicles": [ ... ], "globalStartTime": "2024-02-13T00:00:00.000Z", "globalEndTime": "2024-02-14T06:00:00.000Z" } }
Shipment
Shipment メッセージ タイプは、配送可能な荷物またはルート上で実行可能なサービスのプロパティ構造を定義します。
図に示すように:
Shipmentメッセージには、実際の配送またはサービスに関するすべての情報が含まれています。- すべての
Shipmentメッセージはshipmentsフィールドで指定されます。 shipmentsフィールドには、1 つ以上のShipmentメッセージが含まれます。
Shipment メッセージには、pickups オブジェクトまたは deliveries オブジェクトが少なくとも 1 つ必要です。これらのオブジェクトの定義は次のとおりです。
pickupsは、配送の集荷場所を定義します。deliveriesは、配送の配送先を定義します。pickupsとdeliveriesの両方に、ロケーションなどの詳細を定義するVisitRequestメッセージ タイプが含まれています。
次の表に、Shipment メッセージの pickups と deliveries の構成に基づくさまざまなシナリオを示します。
| シナリオ | 説明 |
|---|---|
pickups のみ |
荷物の集荷のみを行うことを前提としています。 |
deliveries のみ |
配送を事前に読み込んでいるか、サービスを提供していることを前提としています。 |
pickups と deliveries の両方 |
割り当てられた車両は、最初に集荷を完了し、次に配達を完了する必要があります。集荷を行った車両のみが配送を行うことができます。 |
複数の pickups または deliveries |
1 つの配送に pickups または deliveries の複数の候補がリストされている場合、オプティマイザーは、コストを最小限に抑え、制約を満たすことに基づいて、1 つの集荷オプションと 1 つの配送オプションを選択します。 |
Shipment のプロパティの完全なリストについては、リファレンス ドキュメントをご覧ください。
Shipment の例
この例では、犬を自宅から引き取り、デイケアに連れて行く犬のデイケア サービスがあります。2 匹の犬の集荷場所を設定し、配送場所をビジネスに設定するとします。
- 最初の犬の家は、サンフランシスコのコイトタワーにあります。この場所の座標は、緯度 37.8024、経度 -122.4058 です。
- 2 匹目の犬の家は、サンフランシスコのサウス サンセット プレイグラウンド パークにあります。 この場所の座標は、緯度 37.7359、経度 -122.5011 です。
- あなたの犬のデイケアは、サンフランシスコのミッション ドロレス パークにあります。この場所の座標は、緯度 37.759773、経度 -122.427063 です。
次のコードサンプルは Shipment メッセージの例です。shipments オブジェクトには、サンプルの座標を含む 2 つの Shipment メッセージ タイプが含まれています。
{ "model": { "shipments": [ { "pickups": [ { "arrivalLocation": { "latitude": 37.8024, "longitude": -122.4058 } } ], "deliveries": [ { "arrivalLocation": { "latitude": 37.759773, "longitude": -122.427063 } } ] }, { "pickups": [ { "arrivalLocation": { "latitude": 37.7359, "longitude": -122.5011 } } ], "deliveries": [ { "arrivalLocation": { "latitude": 37.759773, "longitude": -122.427063 } } ] } ], "vehicles": [ ... ] } }
Vehicle
Vehicle メッセージ タイプは、ルートで配送を実行できる車両のプロパティ構造を定義します。
図に示すように:
Vehicleメッセージには、実際の車両に関するすべての情報が含まれています。- すべての
Vehicleメッセージはvehiclesフィールドで指定されます。 vehiclesフィールドには、複数のVehicleメッセージが含まれています。
次の表に、Vehicle の関連プロパティを示します。
| プロパティ | 説明 |
|---|---|
startLocation、endLocation |
車両の出発地と目的地。これらは最終的な最適化ルートの一部です。定義されていない場合、デフォルトで最初の配送の集荷場所と最後の配送の配達場所になります。 |
costPerHour、costPerKilometer、costPerTraveledHour |
車両固有の費用パラメータ。API が最適化されたルートを返すようにするには、リクエストに少なくとも 1 つの費用パラメータを含めることをおすすめします。費用の詳細については、費用モデルの主なコンセプトをご覧ください。 |
startTimeWindows、endTimeWindows |
車両がルートを走行できる期間を定義します。これらは、ShipmentModel で設定された globalStartTime と globalEndTime の時間枠内に収まる必要があります。このプロパティは必須ではありませんが、オプティマイザーは時間制約を遵守すると最も効果的に機能するため、含めることをおすすめします。 |
Vehicle の例
この例では、犬のデイケア サービスを運営しており、1 日の開始時と終了時の車両の位置と、消費するガソリンの量を定義します。車両の稼働時間は、ShipmentModel オブジェクト内の globalStartTime プロパティと globalEndTime プロパティで定義した時間と一致するため、指定する必要はありません。
この例では、リクエストの Vehicle プロパティ値は次のとおりです。
| プロパティ | 値 | 説明 |
|---|---|---|
startLocation |
latitude: 37.759773、longitude: -122.427063 |
車両のルートの開始座標。これらは、サンフランシスコのミッション ドロレス パークにある犬のデイケアの場所と一致します。 |
endLocation |
latitude: 37.759773、longitude: -122.427063 |
車両のルートの終了座標。これらは、サンフランシスコのミッション ドロレス パークにある犬のデイケアの場所と一致します。 |
costPerHour |
27 | 犬のデイケア車両を運転するドライバーに支払う金額。ドライバーには 1 時間あたり 27 ドルを支払います。 |
以下は、サンプル シナリオの値を組み込んだ Vehicle メッセージのコードサンプルです。
{ "model": { "shipments": [ ... ], "vehicles": [ { "startLocation": { "latitude": 37.759773, "longitude": -122.427063 }, "endLocation": { "latitude": 37.759773, "longitude": -122.427063 }, "costPerHour": 27 } ] } }
Vehicle のプロパティの完全なリストについては、リファレンス ドキュメントをご覧ください。
リクエストの例
次のコードサンプルは、このドキュメントに示されている ShipmentModel、Shipment、Vehicle の例を組み合わせた、完全なリクエストの例を示しています。
{ "model": { "shipments": [ { "pickups": [ { "arrivalLocation": { "latitude": 37.8024, "longitude": -122.4058 } } ], "deliveries": [ { "arrivalLocation": { "latitude": 37.759773, "longitude": -122.427063 } } ] }, { "pickups": [ { "arrivalLocation": { "latitude": 37.7359, "longitude": -122.5011 } } ], "deliveries": [ { "arrivalLocation": { "latitude": 37.759773, "longitude": -122.427063 } } ] } ], "vehicles": [ { "startLocation": { "latitude": 37.759773, "longitude": -122.427063 }, "endLocation": { "latitude": 37.759773, "longitude": -122.427063 }, "costPerHour": 27 } ], "globalStartTime": "2024-02-13T00:00:00.000Z", "globalEndTime": "2024-02-14T06:00:00.000Z" } }