Base structure (ShipmentModel, Shipment, and Vehicle)

The Route Optimization API's objective is to plan routes for a fleet of vehicles to visit a set of locations. The OptimizeToursRequest object describes the properties of these vehicles and locations and is the primary structure of every endpoint's request body.

The base structure of the OptimizeToursRequest object is as follows:

• The model field holds a ShipmentModel message that contains two key fields:
  • One shipments field, which contains one or several Shipment messages.
  • One vehicles field, which contains one or several Vehicle messages.

This document describes the following message types:

• ShipmentModel: Holds the list of shipments, available vehicles, and other objects that describe their relationships.
• Shipment: Describes locations to be visited by a vehicle. They can represent actual packages to pick up and deliver or places where the vehicle driver performs a service.
• Vehicle: Describes the means of transportation between shipment locations. Each vehicle corresponds to an actual vehicle or a person moving around on foot.

ShipmentModel

ShipmentModel holds the elements of the route optimization problem. It contains a set of shipments that may be performed by a set of vehicles, while considering constraints and minimizing the overall cost.

The table below describes some relevant properties of ShipmentModel:

See the reference documentation for the full list of the properties in ShipmentModel.

ShipmentModel Example

In this example, you have a doggy daycare service and you are starting to build your request. You are defining shipments and vehicles later, but you want to start by setting your business hours and hourly operational cost.

For this example, the ShipmentModel property values in your request are the following:

The following is a code sample of a ShipmentModel message incorporating the example scenario values.

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

Shipment

The Shipment message type defines the property structure of a shipment that can be delivered or service that can be performed on a route.

As illustrated in the diagram:

• A Shipment message has all the information of a real-life shipment or service.
• All Shipment messages are specified in the shipments field.
• The shipments field contains one or many Shipment messages.

A Shipment message requires at least one pickups or deliveries object. The definition of these objects are the following:

• pickups defines the pickup location of a shipment.
• deliveries defines the delivery location of a shipment.
• Both pickups and deliveries contain a VisitRequest message type that defines locations and other details.

The following table describes the different scenarios based on the configuration of pickups and deliveries in a Shipment message.

See the reference documentation for the full list of the properties in Shipment.

Shipment Example

In this example, you have a doggy daycare service where you pick up dogs from their home and deliver them to your daycare. You want to set the pick up location of two dogs, and set their delivery location to your business:

• The first dog's home is in Coit Tower, San Francisco. The coordinates to this location are latitude 37.8024 and longitude -122.4058.
• The second dog's home is in South Sunset Playground Park, San Francisco. The coordinates to this location are latitude 37.7359 and longitude -122.5011.
• Your doggy daycare is in Mission Dolores Park, San Francisco. The coordinates to this location are latitude 37.759773 and longitude -122.427063.

The following is a code sample of a Shipment message, where the shipments object contains two Shipmentmessage types with the example coordinates.

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

The Vehicle message type defines the property structure of a vehicle that can perform a shipment in a route.

As illustrated in the diagram:

• A Vehicle message has all the information of a real-life vehicle.
• All Vehicle messages are specified in the vehicles field.
• The vehicles field contains multiple Vehicle messages.

The following table describes some relevant properties of a Vehicle.

Vehicle Example

In this example, you have a doggy daycare service and you want to define the location of your vehicle's at the start and end of the day and how much gas it spends. You don't need to specify the vehicle's working hours because they match the hours you defined in the globalStartTime and globalEndTime properties within the ShipmentModel object.

For this example, the Vehicle property values in your request are the following:

The following is a code sample of a Vehicle message incorporating the example scenario values.

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

See the reference documentation for the full list of the properties in Vehicle.

Complete request example

The following code sample provides a complete request example, combining the ShipmentModel, Shipment, and Vehicle examples shown in this document.

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