Interpretowanie odpowiedzi interfejsu Route Optimization API… z psami

Po wysłaniu żądania w sekcji Wyślij pierwsze żądanie optymalizator zwraca obiekt OptimizeToursResponse. Odpowiedź to plan trasy, którą ma pokonać kierowca. Z tego przewodnika dowiesz się, jak go odczytywać.

Podsumowanie planu trasy

W przypadku scenariusza z opieką nad psami optymalizator przypisuje do furgonetki berneńskiego psa pasterskiego i chihuahua, a pomija owczarka niemieckiego. Plan trasy kierowcy:

• Rozpocznij zmianę o 7:55 w żłobku.
• Odbierz berneńskiego psa pasterskiego w pobliżu Coit Tower o 8:20.
• Odbierz Chihuahua z South Sunset Playground Park o 8:58.
• Wróć do żłobka o 9:24 i poczekaj, aż o 9:30 otworzy się okienko odbioru.
• Odstaw berneńskiego psa pasterskiego o 9:30.
• Odstawienie Chihuahua o 9:35.
• Zakończ zmianę o 9:40.

Plan trasy kosztuje 147,22 USD, w tym 100 USD kary za pominięcie owczarka niemieckiego.

Aby sprawdzić wyniki, porównaj swoją odpowiedź z pełną przykładową odpowiedzią. Twoje wyniki mogą się nieco różnić, ponieważ czas podróży i odległość zależą od aktualnych danych o drogach.

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

Struktura odpowiedzi

OptimizeToursResponse składa się z 2 głównych komponentów:

• routes: plan trasy dla każdego pojazdu we flocie, w tym kolejność i godziny odbioru oraz dostawy. Masz 1 furgonetkę, więc jest 1 plan trasy.
• metrics: podsumowanie całego planu trasy, w tym łączny koszt, czas trwania i odległość.

Ponieważ optymalizator pomija owczarka niemieckiego, odpowiedź zawiera też skippedShipments.

W sekcjach poniżej dowiesz się, gdzie w odpowiedzi znajdziesz poszczególne szczegóły podsumowania planu trasy.

Który pojazd obsługuje którą trasę?

Optymalizator generuje plan trasy (tablica routes), który odpowiada kolejności vehicles w żądaniu.

Pole vehicleIndex identyfikuje każdy pojazd na podstawie jego pozycji liczonej od zera, która w przypadku furgonetki wynosi 0. Pola vehicleStartTime i vehicleEndTime informują kierowcę, kiedy ma rozpocząć i zakończyć zmianę.

Route Optimization API zwraca sygnatury czasowe w formacie UTC, oznaczone sufiksem Z, niezależnie od przesunięcia w żądaniu. Aby uzyskać czas w San Francisco, odejmij 8 godzin. W przypadku furgonetki zmiana trwa od 7:55 do 9:40, jak pokazano w tym przykładowym kodzie.

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

Jaka jest kolejność odbioru i wysiadania?

W każdej trasie tablica visits zawiera wszystkie odbiory i dostawy przypisanego pojazdu w porządku chronologicznym.

Wartość shipmentIndex każdej wizyty to pozycja przesyłki w żądaniu, liczona od zera: 0 to berneński pies pasterski, a 1 to chihuahua. Pole shipmentLabel zawiera etykietę ustawioną dla każdej przesyłki.

Aby odróżnić odbiór od dostawy, możesz sprawdzić pola visitType lub isPickup:

• visitType: jednoznacznie definiuje działanie związane z wizytą.
  • Odbiór: visitType = "PICKUP_SHIPMENT"
  • Dostawa: visitType = "DELIVER_SHIPMENT"
• isPickup: pole pomocnicze wartości logicznej.
  • Odbiór: isPickup = true
  • Dostawa: isPickup = false (pominięto w pliku JSON)

Aby określić dokładną sekwencję zdarzeń i oczekiwany czas przybycia do każdej lokalizacji, odczytaj tablicę visits w odpowiedniej kolejności. W tabeli poniżej znajdziesz działania związane z planem trasy na podstawie kolejności i wartości pól shipmentIndex, isPickup lub visitType oraz startTime.

Poniższy przykładowy kod pokazuje, jak odpowiedź dostarcza tę sekwencję:

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

Każda wizyta ma też parametr visitRequestIndex, który jest pozycją (liczoną od zera) opcji odbioru lub dostawy wybranej przez optymalizator dla przesyłki. Każdy pies w tym scenariuszu ma tylko 1 opcję odbioru i 1 opcję dostawy, więc visitRequestIndex to zawsze 0, a odpowiedź pomija tę wartość.

Co się dzieje między wizytami?

W każdej trasie tablica transitions zawiera szczegóły podróży między wizytami. Chociaż visits i transitions to osobne listy, przeplatają się one w czasie w następujący sposób:

1. transitions[0] (podróż samochodem od początku do pierwszej wizyty)
2. visits[0] (pierwsza wizyta)
3. transitions[1] (podróż samochodem od pierwszej do drugiej wizyty)
4. visits[1] (druga wizyta)
5. ...
6. visits[N-1] (ostatnia wizyta, gdzie N to łączna liczba wizyt)
7. transitions[N] (przejazd od ostatniej wizyty do końca)

Możesz śledzić oś czasu trasy, sprawdzając pole startTime w obu tablicach. startTime przejazdu to moment, w którym kierowca rozpoczyna podróż, a startTime wizyty to moment, w którym kierowca rozpoczyna odbiór lub dostawę.

Każde przejście pokazuje oczekiwany czas jazdy i odległość między lokalizacjami. Tabela poniżej mapuje pola transitions i visits na chronologiczne działania na trasie w scenariuszu dotyczącym hotelu dla psów.

Poniższy przykładowy kod pokazuje, jak odpowiedź zawiera tę sekwencję dla transitions[0] i transitions[1]:

{
  "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"
        },
        ...
      ]
    }
  ]
}

Ile kosztuje przejazd tą trasą?

Możesz sprawdzić kilka pól w odpowiedzi, w zależności od tego, czy potrzebujesz kosztu konkretnego pojazdu, czy łącznego kosztu całej floty.

W tabeli poniżej znajdziesz wszystkie sposoby wyszukiwania informacji o kosztach w odpowiedzi:

Koszty określone w polach routeCosts i costs odzwierciedlają ograniczenia kosztów określone w żądaniu. Więcej informacji znajdziesz w dokumencie Kluczowe pojęcie modelu kosztów.

W tym scenariuszu dotyczącym hotelu dla psów, ponieważ masz pominiętą dostawę, koszt na trasę i łączny koszt są różne. Koszt trasy obejmuje tylko koszty związane z tą konkretną trasą (wynagrodzenie kierowcy), a łączny koszt zagregowany obejmuje też karę za pominiętą przesyłkę. Poniższy przykładowy kod pokazuje, gdzie znaleźć te wartości w odpowiedzi:

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

Zgodnie z planem trasy kierowca prowadzi furgonetkę od 7:55 do 9:40, czyli przez około 1 godzinę i 45 minut (6296 sekund). Przy określonej przez Ciebie stawce 27 USD za godzinę koszt trasy wynosi 47, 22 USD. Ponieważ optymalizator pominął dostawę owczarków niemieckich, dodaje on koszt kary w wysokości 100 USD, co daje łączny koszt zagregowany w wysokości 147,22 USD.

Dlaczego dostawa została pominięta?

Optymalizator wyświetla listę wszystkich dostaw, których nie realizuje, w tablicy skippedShipments. To, dlaczego pomija wysyłkę, zależy od tego, czy ustawisz penaltyCost:

• Przesyłki obowiązkowe (brak penaltyCost): optymalizator nigdy nie pomija tych przesyłek tylko dlatego, że są kosztowne. Pominie przesyłkę tylko wtedy, gdy nie będzie mogła dopasować jej do żadnej trasy, na przykład dlatego, że jej okno czasowe koliduje z innymi przesyłkami.
• Opcjonalne dostawy (z penaltyCost): optymalizator może je pominąć, jeśli ich realizacja kosztuje więcej niż kara. Możesz ustawić różne koszty kar, aby nadać niektórym przesyłkom wyższy priorytet.

W tym scenariuszu okno odbioru owczarka niemieckiego koliduje z oknem berneńskiego psa pasterskiego. Wieża Coit i Land's End są oddalone od siebie o 25 minut, więc kierowca nie może odebrać obu pasażerów w ciągu 20 minut. Optymalizator musi pominąć jeden z nich. Ponieważ owczarek niemiecki ma niższy koszt kary (100 PLN w porównaniu z 1000 PLN w przypadku zwykłego klienta), optymalizator pomija go i ponosi karę w wysokości 100 PLN.

Poniższy przykładowy kod pokazuje obiekt skippedShipments w odpowiedzi:

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

Obiekt skippedShipments w odpowiedzi zawiera te pola:

• index: indeks przesyłki w żądaniu liczony od zera (2 oznacza trzecią przesyłkę).
• label: etykieta podana w żądaniu („owczarek niemiecki”).
• penaltyCost: koszt kary określony w żądaniu, który interfejs API dodaje do łącznego kosztu.

Aby zapobiec pomijaniu przesyłki przez optymalizator, poluzuj ograniczenie, które powoduje konflikt. Możesz na przykład poprosić właściciela owczarka niemieckiego o bardziej elastyczny termin odbioru, a następnie zaktualizować timeWindows dla tego odbioru w swojej prośbie.

Pola odpowiedzi w przykładzie

Tabela poniżej zawiera opis wszystkich pól odpowiedzi zwracanych w OptimizeToursResponse w przykładowym scenariuszu. Nie musisz używać wszystkich pól, aby zrozumieć plan trasy, ale możesz je przeanalizować, aby określić, jak dostosować OptimizeToursRequest do potrzeb firmy. Więcej informacji znajdziesz w artykule Cykl życia planu trasy.

Możesz filtrować zawartość według elementu nadrzędnego lub wyszukiwania tekstowego.