Basisstruktur (ShipmentModel, Shipment und Vehicle)

Ziel der Route Optimization API ist es, Routen für eine Flotte von Fahrzeugen zu planen, um eine Reihe von Standorten anzufahren. Das Objekt OptimizeToursRequest beschreibt die Eigenschaften dieser Fahrzeuge und Standorte und ist die primäre Struktur des Anfragetexts jedes Endpunkts.

Die Basisstruktur des Objekts OptimizeToursRequest sieht so aus:

• Das Feld model enthält eine ShipmentModel-Nachricht mit zwei Schlüsselfeldern:
  • Ein shipments Feld mit einer oder mehreren Shipment Nachrichten.
  • Ein Feld vehicles mit einer oder mehreren Vehicle-Nachrichten.

In diesem Dokument werden die folgenden Nachrichtentypen beschrieben:

• ShipmentModel: Enthält die Liste der Sendungen, verfügbaren Fahrzeuge und anderer Objekte, die ihre Beziehungen beschreiben.
• Shipment: Beschreibt Standorte, die von einem Fahrzeug angefahren werden müssen. Sie können tatsächliche Pakete darstellen, die abgeholt und zugestellt werden müssen, oder Orte, an denen der Fahrer des Fahrzeugs eine Dienstleistung erbringt.
• Vehicle: Beschreibt das Transportmittel zwischen den Versand orten. Jedes Fahrzeug entspricht einem tatsächlichen Fahrzeug oder einer Person, die sich zu Fuß bewegt.

ShipmentModel

ShipmentModel enthält die Elemente des Problems der Routenoptimierung. Es enthält eine Reihe von Sendungen, die von einer Reihe von Fahrzeugen ausgeführt werden können, wobei Einschränkungen berücksichtigt und die Gesamtkosten minimiert werden.

In der folgenden Tabelle werden einige relevante Eigenschaften von ShipmentModel beschrieben:

Properties	Beschreibung
shipments und vehicles	Erforderliche Objekte, die die Details einer oder mehrerer Sendungen und Fahrzeuge enthalten.
globalStartTime und globalEndTime	Gibt Start und Ende des Zeitfensters an, in dem alle Fahrzeuge alle Sendungen abschließen müssen. Diese Eigenschaften sind zwar nicht erforderlich, sollten aber angegeben werden , da der Optimizer am besten funktioniert, wenn Zeitbeschränkungen eingehalten werden.

Eine vollständige Liste der Eigenschaften in ShipmentModel finden Sie in der Referenzdokumentation.

ShipmentModel-Beispiel

In diesem Beispiel haben Sie einen Hundetagesbetreuungsdienst und beginnen mit dem Erstellen Ihrer Anfrage. Sie definieren Sendungen und Fahrzeuge später, möchten aber zuerst Ihre Geschäftszeiten und die stündlichen Betriebskosten festlegen.

In diesem Beispiel sind die ShipmentModel Eigenschaftswerte in Ihrer Anfrage die folgenden:

Attribut	Wert	Beschreibung
globalStartTime	2024-02-13T00:00:00.000Z	Startdatum und -zeit der Geschäftszeiten.
globalEndTime	2024-02-14T06:00:00.000Z	Enddatum und -zeit der Geschäftszeiten.

Im Folgenden finden Sie ein Codebeispiel für eine ShipmentModel-Nachricht mit den Werten des Beispielszenarios.

{
  "model": {
    "shipments": [
      ...
    ],
    "vehicles": [
      ...
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

Shipment

Der Shipment Nachrichtentyp definiert die Struktur der Eigenschaften einer Sendung, die zugestellt werden kann, oder einer Dienstleistung, die auf einer Route ausgeführt werden kann.

Wie im Diagramm dargestellt:

• Eine Shipment-Nachricht enthält alle Informationen zu einer tatsächlichen Sendung oder Dienstleistung.
• Alle Shipment-Nachrichten werden im Feld shipments angegeben.
• Das shipments Feld enthält eine oder mehrere Shipment Nachrichten.

Für eine Shipment-Nachricht ist mindestens ein pickups- oder deliveries-Objekt erforderlich. Die Definitionen dieser Objekte sind die folgenden:

• pickups definiert den Abholort einer Sendung.
• deliveries definiert den Zustellort einer Sendung.
• Sowohl pickups als auch deliveries enthalten einen VisitRequest-Nachrichtentyp, der Standorte und andere Details definiert.

In der folgenden Tabelle werden die verschiedenen Szenarien basierend auf der Konfiguration von pickups und deliveries in einer Shipment-Nachricht beschrieben.

Szenario	Beschreibung
Nur pickups	Es wird davon ausgegangen, dass Sie nur die Sendung abholen.
Nur deliveries	Es wird davon ausgegangen, dass Sie die Sendung vorab geladen haben oder eine Dienstleistung erbringen.
Sowohl pickups als auch deliveries	Das zugewiesene Fahrzeug muss zuerst die Abholung und dann die Zustellung durchführen. Nur das Fahrzeug, das die Abholung durchgeführt hat, kann die Zustellung durchführen.
Mehrere pickups oder deliveries	Wenn für eine Sendung mehrere Möglichkeiten für pickups oder deliveries aufgeführt sind, wählt der Optimizer eine Abhol- und eine Zustelloption aus, um die Kosten zu minimieren und die Einschränkungen zu erfüllen.

Eine vollständige Liste der Eigenschaften in Shipment finden Sie in der Referenzdokumentation.

Shipment-Beispiel

In diesem Beispiel haben Sie einen Hundetagesbetreuungsdienst, bei dem Sie Hunde von zu Hause abholen und zu Ihrer Tagesbetreuung bringen. Sie möchten den Abholort von zwei Hunden festlegen und den Zustellort auf Ihr Unternehmen festlegen:

• Das Haus des ersten Hundes befindet sich im Coit Tower in San Francisco. Die Koordinaten dieses Standorts sind 37,8024 Breitengrad und -122,4058 Längengrad.
• Das Haus des zweiten Hundes befindet sich im South Sunset Playground Park in San Francisco. Die Koordinaten dieses Standorts sind 37,7359 Breitengrad und -122,5011 Längengrad.
• Ihre Hundetagesbetreuung befindet sich im Mission Dolores Park in San Francisco. Die Koordinaten dieses Standorts sind 37,759773 Breitengrad und -122,427063 Längengrad.

Im Folgenden finden Sie ein Codebeispiel für eine Shipment-Nachricht, wobei das Objekt shipments zwei Shipment-Nachrichtentypen mit den Beispielkoordinaten enthält.

{
  "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

Der Vehicle Nachrichtentyp definiert die Struktur der Eigenschaften eines Fahrzeugs, das eine Sendung auf einer Route ausführen kann.

Wie im Diagramm dargestellt:

• Eine Vehicle-Nachricht enthält alle Informationen zu einem tatsächlichen Fahrzeug.
• Alle Vehicle-Nachrichten werden im Feld vehicles angegeben.
• Das vehicles Feld enthält mehrere Vehicle Nachrichten.

In der folgenden Tabelle werden einige relevante Eigenschaften eines Vehicle beschrieben.

Properties	Beschreibung
startLocation und endLocation	Der Start- und Endort der Fahrzeuge, die Teil der endgültigen optimierten Route sind. Wenn sie nicht definiert sind, werden standardmäßig die Standorte der ersten Sendungsabholung und der letzten Sendungszustellung verwendet.
costPerHour, costPerKilometer, costPerTraveledHour	Fahrzeugspezifische Kostenparameter. Es wird empfohlen, mindestens einen Kostenparameter in Ihre Anfrage aufzunehmen, damit die API eine optimierte Route zurückgeben kann. Weitere Informationen zu Kosten finden Sie unter Schlüsselkonzept: Kostenmodell.
startTimeWindows und endTimeWindows	Definieren Sie die Zeiträume , in denen ein Fahrzeug auf einer Route eingesetzt werden kann. Diese müssen in das Zeitfenster globalStartTime und globalEndTime fallen, das in ShipmentModel festgelegt ist. Diese Eigenschaft ist zwar nicht erforderlich, sollte aber angegeben werden , da der Optimizer am besten funktioniert, wenn Zeitbeschränkungen eingehalten werden.

Vehicle-Beispiel

In diesem Beispiel haben Sie einen Hundetagesbetreuungsdienst und möchten den Standort Ihres Fahrzeugs zu Beginn und am Ende des Tages sowie den Kraftstoffverbrauch festlegen. Sie müssen die Arbeitszeiten des Fahrzeugs nicht angeben, da sie mit den Zeiten übereinstimmen, die Sie in den Eigenschaften globalStartTime und globalEndTime im Objekt ShipmentModel definiert haben.

In diesem Beispiel sind die Vehicle-Eigenschaftswerte in Ihrer Anfrage die folgenden:

Attribut	Wert	Beschreibung
startLocation	latitude: 37.759773, longitude: -122.427063	Die Startkoordinaten der Route für Ihr Fahrzeug. Diese entsprechen dem Standort Ihrer Hundetagesbetreuung im Mission Dolores Park in San Francisco.
endLocation	latitude: 37.759773, longitude: -122.427063	Die Endkoordinaten der Route für Ihr Fahrzeug. Diese entsprechen dem Standort Ihrer Hundetagesbetreuung im Mission Dolores Park in San Francisco.
costPerHour	27	Der Betrag, den Sie einem Fahrer für das Fahren Ihres Hundetagesbetreuungsfahrzeugs zahlen. Sie zahlen dem Fahrer 27 $ pro Stunde.

Im Folgenden finden Sie ein Codebeispiel für eine Vehicle-Nachricht mit den Werten des Beispielszenarios.

{
  "model": {
    "shipments": [
    ...
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ]
  }
}

Eine vollständige Liste der Eigenschaften in Vehicle finden Sie in der Referenzdokumentation.

Vollständiges Beispiel für eine Anfrage

Das folgende Codebeispiel enthält eine vollständige Anfrage, in der die in diesem Dokument gezeigten Beispiele für ShipmentModel, Shipment und Vehicle kombiniert werden.

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