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

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

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

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

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

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

ShipmentModel

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

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

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

ShipmentModel Пример

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

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

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

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

Shipment

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

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

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

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

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

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

Полный список свойств 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 определяет структуру свойств транспортного средства, которое может выполнить доставку по маршруту.

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

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

В таблице ниже описаны некоторые важные свойства элемента Vehicle.

Пример использования разметки типа Vehicle

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

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

Ниже приведен пример кода сообщения 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"
  }
}