基本構造（ShipmentModel、Shipment、Vehicle）

ShipmentModel には、Shipment メッセージ タイプを持つ shipments オブジェクトが 1 つと、Vehicle メッセージ タイプを持つ vehicles オブジェクトが 1 つあります。

Route Optimization API の目的は、一連の場所を訪問するフリート車両のルートを計画することです。OptimizeToursRequest オブジェクトは、これらの車両と場所のプロパティを表します。これは、すべてのエンドポイントのリクエスト本文のメイン構造です。

OptimizeToursRequest オブジェクトのベース構造は次のとおりです。

  • model フィールドには、次の 2 つのキーフィールドを含む ShipmentModel メッセージが格納されます。
    • 1 つの shipments フィールド。これには 1 つ以上の Shipment メッセージが含まれます。
    • 1 つの vehicles フィールド。これには 1 つ以上の Vehicle メッセージが含まれます。

このドキュメントでは、次のメッセージ タイプについて説明します。

  • 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 メッセージ タイプは、配達できる配送またはルートで実行できるサービスのプロパティ構造を定義します。

実際の配送は 1 つの「Shipment」メッセージに相当し、「shipments」オブジェクトに含まれます。

図に示すように、

  • Shipment メッセージには、実際の発送またはサービスに関するすべての情報が含まれます。
  • すべての Shipment メッセージは shipments フィールドで指定します。
  • shipments フィールドには、1 つ以上の Shipment メッセージが含まれます。

Shipment メッセージには、pickups オブジェクトまたは deliveries オブジェクトが少なくとも 1 つ必要です。これらのオブジェクトの定義は次のとおりです。

  • pickups は、荷物の集荷場所を定義します。
  • deliveries は、配送先を定義します。
  • pickups と deliveries の両方には、位置情報などの詳細を定義する VisitRequest メッセージ タイプが含まれています。

次の表に、Shipment メッセージの pickups と deliveries の構成に基づくさまざまなシナリオを示します。

シナリオ 説明
pickups のみ 荷物の回収のみを行うことを前提としています。
deliveries のみ 配送をプリロードしているか、サービスを提供していることを前提としています。
pickups と deliveries の両方 割り当てられた車両は、まず集荷してから配達を完了する必要があります。集荷を行った車両のみが配達を行うことができます。
複数の pickups または deliveries 配送に pickups または deliveries の複数の選択肢がリストされている場合、オプティマイザーは、費用を最小限に抑え、制約を満たすために、使用する集荷オプションと配送オプションを 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 メッセージ タイプは、ルートで配送を実行できる車両のプロパティ構造を定義します。

実際の車両は 1 つの「Vehicle」メッセージに相当し、「vehicles」オブジェクトに含まれます。

図に示すように、

  • 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"
  }
}