Базовая структура (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"
  }
}