Интерпретация ответа Route Optimization API… с собаками

После того как вы отправите запрос, как описано в разделе Как отправить первый запрос, оптимизатор вернет ответ OptimizeToursResponse. Этот ответ представляет собой план маршрута, которому должен следовать ваш водитель. В этом руководстве рассказывается, как его читать.

Сводка по плану маршрута

В сценарии с передержкой собак оптимизатор назначает бернского зенненхунда и чихуахуа в ваш фургон и пропускает немецкую овчарку. Маршрут водителя:

• Начать смену в 7:55 в детском саду.
• Забрать бернского зенненхунда у башни Койт в 8:20.
• Забрать чихуахуа в парке Саут-Сансет-Плейграунд в 8:58.
• Вернуться в детский сад в 9:24 и подождать до 9:30, когда откроется окно приема детей.
• Привезите бернского зенненхунда в 9:30.
• Отвезти чихуахуа к 9:35.
• Завершение смены в 9:40.

Стоимость маршрута составляет 147,22 доллара США, включая штраф в размере 100 долларов США за пропуск немецкой овчарки.

Чтобы проверить результаты, сравните свой ответ с полным примером ответа. Ваши результаты могут немного отличаться, поскольку время в пути и расстояние зависят от текущих данных о дорогах.

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

Структура ответа

OptimizeToursResponse состоит из двух основных компонентов:

• routes – план маршрута для каждого транспортного средства в вашем автопарке, включая порядок и время для каждого получения и доставки. У вас один фургон, поэтому есть один план маршрута.
• metrics – сводка по всему маршруту, включая общую стоимость, продолжительность и расстояние.

Поскольку оптимизатор пропускает немецкую овчарку, ответ также включает skippedShipments.

В следующих разделах показано, где в ответе найти каждую деталь сводки плана маршрута.

какое транспортное средство обслуживает тот или иной маршрут;

Оптимизатор генерирует план маршрута (массив routes), который соответствует порядку vehicles в вашем запросе.

Поле vehicleIndex идентифицирует каждое транспортное средство на основе его позиции, отсчитываемой от нуля. Для вашего фургона это 0. Поля vehicleStartTime и vehicleEndTime указывают водителю, когда начинать и заканчивать смену.

Route Optimization API возвращает временные метки в формате UTC, отмеченные суффиксом Z, независимо от смещения в запросе. Чтобы узнать время в Сан-Франциско, вычтите 8 часов. Для фургона смена длится с 7:55 до 9:40, как показано в следующем примере кода.

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

В каком порядке нужно забирать и высаживать пассажиров?

Внутри каждого маршрута массив visits содержит все пункты получения и доставки для назначенного транспортного средства в хронологическом порядке.

Значение shipmentIndex каждого посещения – это позиция доставки в запросе, начиная с нуля: 0 – бернский зенненхунд, а 1 – чихуахуа. В поле shipmentLabel указывается ярлык, который вы задали для каждой доставки.

Чтобы отличить посадку от высадки (или доставку от получения), проверьте поля visitType или isPickup:

• visitType – явным образом определяет действие посещения.
  • Самовывоз: visitType = "PICKUP_SHIPMENT"
  • Доставка: visitType = "DELIVER_SHIPMENT"
• isPickup – вспомогательное поле с логическим значением.
  • Самовывоз: isPickup = true
  • Доставка: isPickup = false (пропущено в JSON)

Чтобы определить точную последовательность событий и ожидаемое время прибытия в каждое место, прочитайте массив visits по порядку. В таблице ниже показано, как действия в плане маршрута зависят от порядка и значений полей shipmentIndex, isPickup или visitType и startTime.

В приведенном ниже фрагменте кода показано, как ответ обеспечивает эту последовательность:

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

У каждого посещения также есть visitRequestIndex – индекс (начиная с нуля) варианта получения или доставки, выбранного оптимизатором для отправления. У каждой собаки в этом сценарии есть только один вариант посадки и один вариант высадки, поэтому visitRequestIndex всегда равен 0, и в ответе он опускается.

Что происходит между посещениями?

В каждом маршруте массив transitions содержит сведения о поездках между посещениями. Хотя visits и transitions – это разные списки, они чередуются во времени следующим образом:

1. transitions[0] (поездка от начала до первого посещения)
2. visits[0] (первое посещение)
3. transitions[1] (стимулирование повторных посещений)
4. visits[1] (второе посещение)
5. ...
6. visits[N-1] (последнее посещение, где N – общее количество посещений)
7. transitions[N] (поездка от места последнего посещения до конечной точки)

Вы можете отслеживать хронологию маршрута, просматривая поле startTime в обоих массивах. startTime перехода – это время, когда водитель начинает движение, а startTime посещения – время, когда водитель начинает посадку или высадку.

Для каждого перехода указывается ожидаемое время в пути и расстояние между местоположениями. В таблице ниже показано, как поля transitions и visits сопоставляются с хронологическими действиями на маршруте для сценария с детским садом для собак.

В приведенном ниже примере кода показано, как ответ предоставляет эту последовательность для transitions[0] и 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"
        },
        ...
      ]
    }
  ]
}

Сколько стоит проезд по маршруту?

В ответе можно посмотреть несколько полей в зависимости от того, нужна ли вам стоимость для конкретного транспортного средства или общая стоимость для всего автопарка.

В таблице ниже перечислены все способы найти информацию о стоимости в ответе.

Расходы, указанные в полях routeCosts и costs, отражают ограничения расходов, которые вы задаете в запросе. Дополнительную информацию можно найти в статье Основные понятия модели затрат.

В этом сценарии с передержкой собак, поскольку у вас есть пропущенная доставка, стоимость маршрута и общая стоимость различаются. Стоимость маршрута включает только расходы, связанные с этим конкретным маршрутом (заработная плата водителя), в то время как общая совокупная стоимость также включает штраф за пропущенную доставку. В приведенном ниже примере кода показано, где найти эти значения в ответе.

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

Согласно плану маршрута, водитель управляет фургоном с 7:55 до 9:40, то есть примерно 1 час и 45 минут (6296 секунд). При заданной вами ставке 27 долларов США в час стоимость маршрута составляет 47, 22 доллара США. Поскольку оптимизатор пропустил доставку немецкой овчарки, он добавляет штрафную стоимость в размере 100 долларов США, в результате чего общая совокупная стоимость составляет 147,22 доллара США.

Почему отправка была пропущена?

Оптимизатор перечисляет все невыполненные отправки в массиве skippedShipments. Причина пропуска зависит от того, задали ли вы penaltyCost:

• Обязательные перевозки (без penaltyCost). Оптимизатор никогда не пропускает их только потому, что они дорогие. Пропуск возможен, только если отправление не удается включить ни в один маршрут, например из-за того, что его временное окно конфликтует с другими отправлениями.
• Необязательные перевозки (с penaltyCost). Оптимизатор может пропускать их, если стоимость их выполнения превышает штраф. Вы можете задать разные штрафы, чтобы отдать приоритет одним перевозкам перед другими.

В этом сценарии время, когда нужно забрать немецкую овчарку, совпадает со временем, когда нужно забрать бернского зенненхунда. Башня Койт и Лэндс-Энд находятся в 25 минутах езды друг от друга, поэтому водитель не сможет забрать обоих пассажиров в течение 20 минут. Оптимизатор должен пропустить один из них. Поскольку у немецкой овчарки штраф меньше (100 долларов США против 1000 долларов США за обычного клиента), оптимизатор пропускает ее и налагает штраф в размере 100 долларов США.

В приведенном ниже фрагменте кода показан объект skippedShipments в ответе:

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

Объект skippedShipments в ответе содержит следующие поля:

• index – индекс отправления в запросе, отсчитываемый от нуля (2 для третьего отправления).
• label – ярлык, указанный в запросе ("немецкая овчарка").
• penaltyCost – штраф, указанный в запросе. API добавляет его к общей стоимости.

Чтобы оптимизатор не пропускал отправку, ослабьте ограничение, вызывающее конфликт. Например, попросите владельца немецкой овчарки расширить временной интервал для передачи собаки, а затем обновите timeWindows для этой передачи в своем запросе.

Поля ответа в примере

В таблице ниже описаны все поля ответа, возвращаемые в OptimizeToursResponse в примере сценария. Для понимания плана маршрута не обязательно использовать все поля, но вы можете проанализировать их, чтобы определить, как настроить OptimizeToursRequest в соответствии с потребностями вашего бизнеса. Подробнее о жизненном цикле плана маршрута…

Вы можете отфильтровать содержимое по родительскому элементу или с помощью текстового поиска.