Route Optimization API-Antwort interpretieren… mit Hunden

Nachdem Sie die Anfrage unter Erste Anfrage senden gesendet haben, gibt der Optimierer ein OptimizeToursResponse zurück. Diese Antwort ist der Routenplan, dem der Fahrer folgen soll. In diesem Leitfaden erfahren Sie, wie Sie sie lesen.

Zusammenfassung des Routenplans

Im Szenario mit der Hundetagesstätte weist der Optimierer den Berner Sennenhund und den Chihuahua Ihrem Lieferwagen zu und überspringt den Deutschen Schäferhund. Der Routenplan Ihres Fahrers sieht so aus:

• Schicht um 07:55 Uhr in der Kindertagesstätte beginnen.
• Hol den Berner Sennenhund um 08:20 Uhr in der Nähe des Coit Tower ab.
• Hol den Chihuahua um 8:58 Uhr im South Sunset Playground Park ab.
• Sie kommen um 9:24 Uhr wieder bei der Kindertagesstätte an und warten, bis das Zeitfenster für die Abgabe um 9:30 Uhr beginnt.
• Berner Sennenhund um 9:30 Uhr abgeben.
• Chihuahua um 09:35 Uhr abgeben.
• Schichtende um 09:40 Uhr.

Der Routenplan kostet 147,22 $, einschließlich einer Strafe von 100 $ für das Auslassen des Schäferhundes.

Vergleichen Sie Ihre Antwort mit der vollständigen Beispielantwort, um Ihre Ergebnisse zu prüfen. Die Ergebnisse können leicht abweichen, da die Fahrtzeiten und Entfernungen von den aktuellen Straßendaten abhängen.

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "detour": "0s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "detour": "2600s",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "startTime": "2024-02-13T17:30:00Z",
          "detour": "2297s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "startTime": "2024-02-13T17:35:00Z",
          "detour": "656s",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ],
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        {
          "travelDuration": "1252s",
          "travelDistanceMeters": 7860,
          "waitDuration": "356s",
          "totalDuration": "1608s",
          "startTime": "2024-02-13T17:03:12Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:35:00Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:40:00Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 2,
        "travelDuration": "4740s",
        "waitDuration": "356s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "1200s",
        "totalDuration": "6296s",
        "travelDistanceMeters": 31531,
        "performedShipmentPenaltyCostSum": 2000
      },
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22,
      "vehicleFullness": {
        "maxFullness": 0.3497777777777778,
        "activeSpan": 0.3497777777777778
      }
    }
  ],
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 2,
      "travelDuration": "4740s",
      "waitDuration": "356s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "1200s",
      "totalDuration": "6296s",
      "travelDistanceMeters": 31531,
      "performedShipmentPenaltyCostSum": 2000
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T15:55:04Z",
    "latestVehicleEndTime": "2024-02-13T17:40:00Z",
    "totalCost": 147.22,
    "costs": {
      "model.vehicles.cost_per_hour": 47.22,
      "model.shipments.penalty_cost": 100
    }
  }
}
    

Antwortstruktur

Die OptimizeToursResponse enthält zwei Hauptkomponenten:

• routes: Der Routenplan für jedes Fahrzeug in Ihrer Flotte, einschließlich der Reihenfolge und Zeiten für jede Abholung und Lieferung. Sie haben einen Lieferwagen, also gibt es einen Routenplan.
• metrics: Eine Zusammenfassung des gesamten Routenplans, einschließlich der Gesamtkosten, der Dauer und der Entfernung.

Da der Optimierer den Deutschen Schäferhund überspringt, enthält die Antwort auch skippedShipments.

In den folgenden Abschnitten wird gezeigt, wo Sie die einzelnen Details der Zusammenfassung des Routenplans in der Antwort finden.

Welches Fahrzeug fährt welche Route?

Der Optimierer generiert einen Routenplan (das routes-Array), der der Reihenfolge der vehicles in Ihrer Anfrage entspricht.

Im Feld vehicleIndex wird jedes Fahrzeug anhand seiner nullbasierten Position identifiziert, die für Ihren Lieferwagen 0 ist. Die Felder vehicleStartTime und vehicleEndTime geben dem Fahrer an, wann er seine Schicht beginnen und beenden soll.

Die Route Optimization API gibt Zeitstempel in UTC zurück, die mit dem Suffix Z gekennzeichnet sind, unabhängig vom Offset in Ihrer Anfrage. Um die Zeit in San Francisco zu erhalten, subtrahieren Sie 8 Stunden. Für Ihren Lieferwagen dauert die Schicht von 07:55 Uhr bis 09:40 Uhr, wie im folgenden Codebeispiel gezeigt.

{
"routes": [
    {
    // "vehicleIndex": 0, // Omitted in actual JSON response because it's 0
    "vehicleStartTime": "2024-02-13T15:55:04Z",
    "vehicleEndTime": "2024-02-13T17:40:00Z",
    ...
    }
  ]
  ...
}

In welcher Reihenfolge werden die Fahrgäste abgeholt und abgesetzt?

In jeder Route enthält das Array visits alle Abholungen und Lieferungen für das zugewiesene Fahrzeug in chronologischer Reihenfolge.

Die shipmentIndex jedes Besuchs ist die nullbasierte Position der Sendung in Ihrer Anfrage: 0 ist der Berner Sennenhund und 1 ist der Chihuahua. Im Feld shipmentLabel wird das Label angezeigt, das Sie für jede Sendung festgelegt haben.

Um zwischen einer Abholung und einer Abgabe (oder Lieferung) zu unterscheiden, können Sie entweder das Feld visitType oder isPickup prüfen:

• visitType: Definiert die Besuchsaktion explizit.
  • Abholung: visitType = "PICKUP_SHIPMENT"
  • Lieferung: visitType = "DELIVER_SHIPMENT"
• isPickup: Ein boolesches Hilfsfeld.
  • Abholung: isPickup = true
  • Lieferung: isPickup = false (in JSON weggelassen)

Wenn Sie die genaue Abfolge der Ereignisse und die voraussichtliche Ankunftszeit an jedem Ort ermitteln möchten, lesen Sie das Array visits in der richtigen Reihenfolge. In der folgenden Tabelle sehen Sie die Aktion des Routenplans basierend auf der Reihenfolge und den Werten der Felder shipmentIndex, isPickup oder visitType und startTime.

Das folgende Codebeispiel zeigt, wie die Antwort diese Sequenz bereitstellt:

{
  "routes": [
    {
      "visits": [
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:30:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:35:00Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ]
    }
  ]
}

Jeder Besuch hat auch einen visitRequestIndex. Das ist die nullbasierte Position der Abhol- oder Lieferoption, die der Optimierer für die Sendung ausgewählt hat. Jeder Hund in diesem Szenario hat nur eine Abhol- und eine Abgabeoption. Daher ist visitRequestIndex immer 0 und wird in der Antwort weggelassen.

Was passiert zwischen den Besuchen?

Im Array transitions sind für jede Route die Reisedetails zwischen den Besuchen aufgeführt. visits und transitions sind zwar separate Listen, sie sind jedoch zeitlich so verschachtelt:

1. transitions[0] (Fahrt vom Start zum ersten Besuch)
2. visits[0] (Erster Besuch)
3. transitions[1] (Zeit zwischen erstem und zweitem Besuch)
4. visits[1] (zweiter Besuch)
5. ...
6. visits[N-1] (Letzter Besuch, wobei N die Gesamtzahl der Besuche ist)
7. transitions[N] (Fahrt vom letzten Besuch bis zum Ende)

Sie können die Zeitachse der Route anhand des Felds startTime in beiden Arrays verfolgen. Die startTime einer Fahrt ist der Zeitpunkt, an dem der Fahrer losfährt. Die startTime eines Besuchs ist der Zeitpunkt, an dem der Fahrer mit der Abholung oder dem Abliefern beginnt.

Für jeden Übergang werden die voraussichtliche Fahrzeit und die Entfernung zwischen den Standorten angezeigt. In der folgenden Tabelle werden die Felder transitions und visits den chronologischen Routenaktionen für das Szenario mit der Hundetagesstätte zugeordnet.

Das folgende Codebeispiel zeigt, wie die Antwort diese Sequenz für transitions[0] und transitions[1] bereitstellt:

{
  "routes": [
    {
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        ...
      ]
    }
  ]
}

Wie viel kostet die Route?

Je nachdem, ob Sie die Kosten für ein bestimmtes Fahrzeug oder die Gesamtkosten für die gesamte Flotte benötigen, können Sie sich mehrere Felder in der Antwort ansehen.

In der folgenden Tabelle sind alle Möglichkeiten aufgeführt, wie Sie Kosteninformationen in der Antwort finden können:

Die in routeCosts und costs angegebenen Kosten entsprechen den Kosteneinschränkungen, die Sie in Ihrer Anfrage angeben. Weitere Informationen finden Sie im Dokument Schlüsselkonzept des Kostenmodells.

In diesem Szenario mit der Hundetagesstätte unterscheiden sich die Kosten pro Route und die aggregierten Gesamtkosten, da eine Sendung übersprungen wurde. Die Routenkosten umfassen nur die Kosten, die mit dieser bestimmten Route verbunden sind (der Lohn des Fahrers), während die aggregierten Gesamtkosten auch die Strafe für die übersprungene Sendung enthalten. Das folgende Codebeispiel zeigt, wo diese Werte in der Antwort zu finden sind:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      ...
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22
    }
  ],
  "metrics": {
    "totalCost": 147.22,
    "costs": {
      "model.shipments.penalty_cost": 100,
      "model.vehicles.cost_per_hour": 47.22
    },
    ...
  }
}

Laut Routenplan fährt der Fahrer den Transporter von 7:55 Uhr bis 9:40 Uhr, also etwa 1 Stunde und 45 Minuten (6.296 Sekunden). Bei Ihrem festgelegten Satz von 27 $ pro Stunde betragen die Kosten für die Route 47, 22 $. Da der Optimierer die Lieferung mit dem Deutschen Schäferhund übersprungen hat, werden Strafkosten in Höhe von 100 $ hinzugefügt.Die Gesamtkosten belaufen sich somit auf 147, 22 $.

Warum wurde eine Sendung übersprungen?

Der Optimierer listet alle Sendungen, die er nicht ausführt, im Array skippedShipments auf. Warum eine Sendung übersprungen wird, hängt davon ab, ob Sie einen penaltyCost festgelegt haben:

• Obligatorische Lieferungen (kein penaltyCost): Der Optimierer überspringt diese nie, nur weil sie teuer sind. Eine Sendung wird nur dann übersprungen, wenn sie in keine Route passt, z. B. weil ihr Zeitfenster mit anderen Sendungen in Konflikt steht.
• Optionale Sendungen (mit penaltyCost): Der Optimierer kann diese auch überspringen, wenn die Ausführung mehr kostet als die Strafe. Sie können unterschiedliche Strafkosten festlegen, um bestimmte Sendungen gegenüber anderen zu priorisieren.

In diesem Szenario überschneidet sich das Abholfenster des Schäferhunds mit dem des Berner Sennenhunds. Der Coit Tower und Land's End sind 25 Minuten voneinander entfernt. Der Fahrer kann also nicht beide Abholungen innerhalb des 20-minütigen Zeitfensters erledigen. Der Optimierer muss einen davon überspringen. Da der Deutsche Schäferhund die geringeren Strafkosten hat (100 $ gegenüber 1.000 $ für den regulären Kunden), überspringt der Optimierer ihn und es fallen die Strafkosten von 100 $ an.

Das folgende Codebeispiel zeigt das skippedShipments-Objekt in der Antwort:

{
  ...
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  ...
}

Das Objekt skippedShipments in der Antwort enthält die folgenden Felder:

• index: Der nullbasierte Index der Sendung in Ihrer Anfrage (2 für die dritte Sendung).
• label: Das Label, das Sie in der Anfrage angegeben haben („Deutscher Schäferhund“).
• penaltyCost: Die in der Anfrage angegebenen Strafkosten, die von der API zu den Gesamtkosten hinzugefügt werden.

Damit der Optimierer eine Sendung nicht überspringt, lockern Sie die Einschränkung, die den Konflikt verursacht. Sie können beispielsweise den Besitzer des Schäferhundes um ein flexibleres Abholfenster bitten und dann das timeWindows für diese Abholung in Ihrer Anfrage aktualisieren.

Antwortfelder im Beispiel

In der folgenden Tabelle werden alle Antwortfelder beschrieben, die im OptimizeToursResponse des Beispielszenarios zurückgegeben werden. Sie müssen nicht jedes Feld verwenden, um den Routenplan zu verstehen. Sie können diese Felder jedoch analysieren, um festzustellen, wie Sie Ihre OptimizeToursRequest an Ihre geschäftlichen Anforderungen anpassen können. Weitere Informationen finden Sie unter Lebenszyklus des Routenplans.

Sie können die Inhalte nach übergeordnetem Element oder per Textsuche filtern.