Basisstruktur (ShipmentModel, Shipment und Vehicle)

Mit der Route Optimization API lassen sich Routen für eine Fahrzeugflotte planen, um eine Reihe von Standorten anzufahren. Das OptimizeToursRequest-Objekt beschreibt die Eigenschaften dieser Fahrzeuge und Standorte und ist die primäre Struktur des Anfrage-Bodys jedes Endpunkts.

Die Basisstruktur des OptimizeToursRequest-Objekts sieht so aus:

• Das Feld model enthält eine ShipmentModel-Nachricht mit zwei Schlüsselfeldern:
  • Ein shipments-Feld, das eine oder mehrere Shipment-Meldungen enthält.
  • Ein vehicles-Feld, das eine oder mehrere Vehicle-Meldungen enthält.

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 Orte, die von einem Fahrzeug besucht werden sollen. 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 die Transportmittel zwischen den Versandorten. 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. Sie 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 Attribute von ShipmentModel beschrieben:

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

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

Beispiel für ShipmentModel

In diesem Beispiel haben Sie einen Hundetagesbetreuungsdienst und beginnen mit der Erstellung 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 Werte der ShipmentModel-Eigenschaft in Ihrer Anfrage die folgenden:

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

Im Folgenden finden Sie ein Codebeispiel für eine ShipmentModel-Nachricht mit den Werten aus dem Beispielszenario.

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

Shipment

Der Nachrichtentyp Shipment definiert die Attributstruktur einer Sendung, die auf einer Route zugestellt werden kann, oder eines Dienstes, der auf einer Route ausgeführt werden kann.

Wie im Diagramm dargestellt:

• Eine Shipment-Nachricht enthält alle Informationen zu einer echten Sendung oder Dienstleistung.
• Alle Shipment-Nachrichten werden im Feld shipments angegeben.
• Das Feld shipments 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:

• pickups definiert den Abholort einer Sendung.
• deliveries definiert den Lieferort einer Sendung.
• Sowohl pickups als auch deliveries enthalten den Nachrichtentyp VisitRequest, 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 Lieferung durchführen. Nur das Fahrzeug, mit dem die Abholung erfolgt ist, kann die Lieferung 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 Optimierer eine Abhol- und eine Lieferoption aus, um die Kosten zu minimieren und die Einschränkungen zu erfüllen.

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

Beispiel für Shipment

In diesem Beispiel bieten Sie eine Hundetagesstätte an, in der Sie Hunde von zu Hause abholen und zu Ihrer Tagesstätte bringen. Sie möchten den Abholort von zwei Hunden und den Lieferort für Ihr Unternehmen festlegen:

• Das erste Zuhause des Hundes befindet sich im Coit Tower in San Francisco. Die Koordinaten dieses Standorts sind 37,8024 Breitengrad und -122,4058 Längengrad.
• Das zweite Zuhause des Hundes befindet sich im South Sunset Playground Park in San Francisco. Die Koordinaten für diesen Ort sind 37,7359 Breitengrad und -122,5011 Längengrad.
• Ihre Hundetagesstätte befindet sich im Mission Dolores Park in San Francisco. Die Koordinaten dieses Standorts sind Breitengrad 37,759773 und Längengrad -122,427063.

Im Folgenden finden Sie ein Codebeispiel für eine Shipment-Nachricht, in der das shipments-Objekt 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 Nachrichtentyp Vehicle definiert die Attributstruktur eines Fahrzeugs, das eine Lieferung auf einer Route ausführen kann.

Wie im Diagramm dargestellt:

• Eine Vehicle-Nachricht enthält alle Informationen eines echten Fahrzeugs.
• Alle Vehicle-Nachrichten werden im Feld vehicles angegeben.
• Das Feld vehicles enthält mehrere Vehicle-Nachrichten.

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

Attribute	Beschreibung
startLocation und endLocation	Der Start- und Zielort der Fahrzeuge, die Teil der endgültigen optimierten Route sind. Wenn sie nicht definiert sind, werden standardmäßig die Standorte für die erste Abholung und die letzte Zustellung verwendet.
costPerHour, costPerKilometer, costPerTraveledHour	Fahrzeugspezifische Kostenparameter. Es wird empfohlen, dass Sie mindestens einen Kostenparameter in Ihre Anfrage aufnehmen, damit die API eine optimierte Route zurückgibt. Weitere Informationen zu Kosten finden Sie unter Kostenmodell.
startTimeWindows und endTimeWindows	Definieren Sie die Zeiträume, in denen ein Fahrzeug auf einer Route verkehren kann. Sie müssen innerhalb des in ShipmentModel festgelegten Zeitfensters zwischen globalStartTime und globalEndTime liegen. Diese Property ist zwar nicht erforderlich, wird aber empfohlen, da der Optimizer am besten funktioniert, wenn Zeitbeschränkungen eingehalten werden.

Beispiel für Vehicle

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

In diesem Beispiel sind die Werte der Vehicle-Eigenschaft 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 Hundetagesstätte im Mission Dolores Park in San Francisco.
endLocation	latitude: 37.759773, longitude: -122.427063	Die Koordinaten des Endpunkts der Route für Ihr Fahrzeug. Diese entsprechen dem Standort Ihrer Hundetagesstätte im Mission Dolores Park in San Francisco.
costPerHour	27	Wie viel Sie einem Fahrer für das Fahren Ihres Fahrzeugs für die Hundetagesstätte bezahlen. Sie zahlen dem Fahrer 27 $ pro Stunde.

Im Folgenden finden Sie ein Codebeispiel für eine Vehicle-Nachricht mit den Werten aus dem Beispielszenario.

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

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

Beispiel für eine vollständige Anfrage

Das folgende Codebeispiel enthält ein vollständiges Anfragebeispiel, in dem 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"
  }
}