Базовая структура (ShipmentModel, Shipment и Vehicle)

ShipmentModel has one `shipments` object with a `Shipment` message type and one `vehicles` object with a `Vehicle` message type.

Цель API оптимизации маршрутов — планирование маршрутов для парка транспортных средств с посещением набора локаций. Объект OptimizeToursRequest описывает свойства этих транспортных средств и локаций и является основной структурой тела запроса каждой конечной точки.

Базовая структура объекта OptimizeToursRequest выглядит следующим образом:

  • Поле model содержит сообщение ShipmentModel , содержащее два ключевых поля:
    • Одно поле shipments , которое содержит одно или несколько сообщений Shipment .
    • Одно поле vehicles , которое содержит одно или несколько сообщений Vehicle .

В этом документе описываются следующие типы сообщений:

  • ShipmentModel : содержит список поставок, доступных транспортных средств и других объектов, описывающих их взаимосвязи.
  • Shipment : описывает места, которые должен посетить автомобиль. Это могут быть реальные посылки, которые нужно забрать и доставить, или места, где водитель транспортного средства оказывает услуги.
  • Vehicle : описывает средство передвижения между пунктами отправки. Каждое транспортное средство соответствует реальному транспортному средству или человеку, передвигающемуся пешком.

ShipmentModel

ShipmentModel содержит элементы задачи оптимизации маршрута. Она содержит набор перевозок, которые могут быть выполнены группой транспортных средств с учётом ограничений и минимизацией общей стоимости.

В таблице ниже описаны некоторые важные свойства ShipmentModel :

Характеристики Описание
shipments и vehicles Обязательные объекты, содержащие сведения об одной или нескольких партиях и транспортных средствах .
globalStartTime и globalEndTime Указывает начало и конец временного интервала, в течение которого все транспортные средства должны завершить все перевозки. Хотя эти свойства не являются обязательными, рекомендуется их включить, поскольку оптимизатор работает лучше всего при соблюдении временных ограничений.

Полный список свойств ShipmentModel см. в справочной документации.

Пример ShipmentModel

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

Для этого примера значения свойства ShipmentModel в вашем запросе следующие:

Свойство Ценить Описание
globalStartTime 2024-02-13T00:00:00.000Z Дата и время начала рабочего дня.
globalEndTime 2024-02-14T06:00:00.000Z Дата и время окончания рабочего времени.

Ниже приведен пример кода сообщения ShipmentModel , включающего значения примера сценария.

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

Shipment

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

A real life shipment equals one `Shipment` message, which is contained within a `shipments` object

Как показано на диаграмме:

  • Сообщение Shipment содержит всю информацию о реальной отправке или услуге.
  • Все сообщения Shipment указаны в поле shipments .
  • Поле shipments содержит одно или несколько сообщений Shipment .

Для сообщения Shipment требуется как минимум один объект pickups или deliveries . Определение этих объектов следующее:

  • pickups определяет место забора груза.
  • deliveries определяет место доставки груза.
  • Как pickups , так и deliveries содержат тип сообщения VisitRequest , который определяет местоположения и другие детали.

В следующей таблице описываются различные сценарии, основанные на конфигурации pickups и deliveries в сообщении Shipment .

Сценарий Описание
только pickups Предполагается, что вы только забираете груз .
только deliveries Предполагается, что вы предварительно загрузили груз или оказываете услугу .
Как pickups , так и deliveries Выделенное транспортное средство должно сначала осуществить забор груза, а затем доставку . Доставку может выполнить только транспортное средство, выполнившее забор груза.
Несколько pickups или deliveries Если для отправки указано несколько вариантов pickups или deliveries , оптимизатор выбирает один вариант забора и один вариант доставки , исходя из минимизации затрат и соблюдения ограничений.

Полный список свойств см. в справочной документации в Shipment .

Пример Shipment

В этом примере вы предлагаете услуги по уходу за собаками, где вы забираете собак из дома и доставляете их в свой детский сад. Вы хотите указать место, где забрать двух собак, и указать место доставки в свою компанию:

  • Дом первой собаки находится в Койт-Тауэр, Сан-Франциско. Координаты этого места: широта 37,8024 и долгота -122,4058.
  • Дом второй собаки находится в парке South Sunset Playground в Сан-Франциско. Координаты этого места: широта 37.7359 и долгота -122.5011.
  • Ваш собачий дневной питомник находится в Мишн-Долорес-Парке, Сан-Франциско. Координаты этого места: широта 37.759773 и долгота -122.427063.

Ниже приведен пример кода сообщения Shipment , где объект shipments содержит два типа сообщений Shipment с примерами координат.

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

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

A real life vehicle equals one `Vehicle` message, which is contained within a `vehicles` object

Как показано на диаграмме:

  • Сообщение Vehicle содержит всю информацию о реальном транспортном средстве.
  • Все сообщения Vehicle указаны в поле vehicles .
  • Поле vehicles содержит несколько сообщений Vehicle .

В следующей таблице описываются некоторые важные свойства Vehicle .

Характеристики Описание
startLocation и endLocation Начальное и конечное местоположение транспортных средств, входящих в финальный оптимизированный маршрут. Если не указано, по умолчанию используются первое место забора и последнее место доставки груза.
costPerHour , costPerKilometer , costPerTraveledHour Параметры стоимости, специфичные для транспортного средства. Рекомендуется указать хотя бы один параметр стоимости в запросе API, чтобы получить оптимизированный маршрут. Подробнее о стоимости см. в разделе «Ключевая концепция модели стоимости» .
startTimeWindows и endTimeWindows Определите периоды времени , в течение которых транспортное средство может работать на маршруте. Они должны попадать в интервалы globalStartTime и globalEndTime , заданные в ShipmentModel . Хотя это свойство не является обязательным, рекомендуется его включить, поскольку оптимизатор работает лучше всего при соблюдении временных ограничений.

Пример Vehicle

В этом примере у вас есть служба дневного пребывания собак, и вы хотите определить местоположение вашего автомобиля в начале и конце дня, а также расход топлива. Вам не нужно указывать часы работы автомобиля, поскольку они соответствуют часам, заданным в свойствах globalStartTime и globalEndTime объекта ShipmentModel .

Для этого примера значения свойств Vehicle в вашем запросе следующие:

Свойство Ценить Описание
startLocation latitude : 37.759773, longitude : -122.427063 Начальные координаты маршрута вашего транспортного средства. Они соответствуют местоположению вашего питомника для собак, расположенного в парке Мишн-Долорес в Сан-Франциско.
endLocation latitude : 37.759773, longitude : -122.427063 Конечные координаты маршрута вашего транспортного средства. Они соответствуют местоположению вашего питомника для собак, расположенного в парке Мишн-Долорес в Сан-Франциско.
costPerHour 27 Сколько вы платите водителю за управление вашим детским садом для собак? Вы платите водителю 27 долларов в час.

Ниже приведен пример кода сообщения Vehicle , включающий значения примера сценария.

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

Полный список свойств в Vehicle см. в справочной документации.

Полный пример запроса

Следующий пример кода представляет собой полный пример запроса, объединяющий примеры ShipmentModel , Shipment и Vehicle показанные в этом документе.

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