Construct a request message

European Economic Area (EEA) developers

As briefly described in Route Optimization Overview, a basic request consists of Model, Shipments, and Vehicles as required entities:

  • Model captures settings and constraints for the entire request, inclusive of both Shipments and Vehicles.
  • Shipments represent tasks or actual shipments that include pickup and delivery VisitRequests. Shipments have local settings and constraints.
  • Vehicles represent vehicles, drivers, or personnel. Vehicles also have local settings and constraints.

Each entity's properties describe part of an optimization problem at a particular level of granularity. Model-wide constraints are applied to all shipments and vehicles, while constraints and properties specified on shipments or vehicles are specific to a single shipment or vehicle.

For complete documentation on each message type, see the reference documentation for ShipmentModel (REST, gRPC), Shipment (REST, gRPC), and Vehicle (REST, gRPC) messages.

OptimizeToursRequest properties

Some commonly used properties of the top-level OptimizeToursRequest message (REST, gRPC) include the following:

  • searchMode indicates whether to return the first solution that satisfies specified constraints or find the best possible solution within a set deadline.
  • considerRoadTraffic determines whether or not live traffic is used for routing and ETA estimation.
  • populateTransitionPolylines determines whether or not route polylines and route tokens are returned in the response.

Model properties

Some commonly used properties of the ShipmentModel message (REST, gRPC) include:

  • globalStartTime represents the earliest start time of routes across all vehicles and shipments. No vehicle may start its first transitions and shipments before this time.
  • globalEndTime represents the latest end time of routes across all vehicles and shipments. All assigned shipments and transitions must be complete before this time.

Shipment properties

Some commonly used properties of the Shipment message (REST, gRPC) include:

  • pickups[] and deliveries[] represent where a shipment can be picked up or dropped off. pickups[] and deliveries[] properties both use the VisitRequest message (REST, gRPC).
  • loadDemands represent the load required for a vehicle to complete a shipment. Vehicles' corresponding load_limits (REST, gRPC) property represents how much load a vehicle can accommodate at one time. Read more about load in Load Demands and Limits.
  • penalty_cost represents the cost incurred if a shipment is skipped. Read more on costs in Cost Model Parameters.

Vehicle properties

Some commonly used properties of the Vehicle message (REST, gRPC) include:

  • startLocation represents where a vehicle must start its route. This property is optional. If not specified, the vehicle's route starts at the location of its first assigned shipment.
  • endLocation represents where a vehicle must end its route. This property is optional. If not specified, the vehicle's route ends at the location of its last assigned shipment.
  • startTimeWindows[] represents when a vehicle can start its route. This property is optional.
  • endTimeWindows[] represents when a vehicle can start and end its route. Both properties are optional.
  • loadLimits represent the vehicle's capacity available to meet shipments' load demands. Read more about load demands and limits in Load Demands and Limits.

A complete example request in JSON format looks like:

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.73881799999999,
              "longitude": -122.4161
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.79581,
              "longitude": -122.4218856
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.73881799999999,
          "longitude": -122.4161
        },
        "endLocation": {
          "latitude": 37.73881799999999,
          "longitude": -122.4161
        },
        "costPerKilometer": 1.0
      }
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

OptimizeTours and BatchOptimizeTours both consume request messages like the example above, but in different ways. Before making a Route Optimization request, it's important to understand the difference between the two methods:

Comparing OptimizeTours and BatchOptimizeTours