Interpret the response

The Route Optimization API returns routes for vehicles in the corresponding request. Shipments are assigned to vehicles, or may be skipped depending on the request's properties.

An OptimizeToursResponse message (REST, gRPC) has two main top-level properties:

• routes[] are the routes for each vehicle with its assigned shipments. Each Route contains metrics reflecting properties of that individual route.
• metrics are aggregated metrics for the entire response, across all vehicles and route plans. Top-level metrics contain the same properties as per-Route metrics, with values aggregated across all Routes.

Some properties may not always be populated depending on optimization results:

1. skippedShipments[] lists shipments that are not performed by any vehicle. A shipment can be skipped if it cannot be performed within specified constraints or if the cost to perform the shipment exceeds its penalty cost. For example, if a shipment's pickup or delivery has a very narrow timeWindow it may not be possible or cost effective for a vehicle to perform the visit during the required time window.
2. validationErrors[] specifies errors that makes the request invalid or impossible to solve when the request's solvingMode is set to VALIDATE_ONLY. In normal DEFAULT_SOLVE mode, validation errors will appear in an error message instead of the response body. Note that VALIDATE_ONLY solving mode can report multiple errors at once, which is useful for quickly debugging requests.

Note: to interpret a response, the corresponding request is needed. The response contains references to entities in the request, making the response difficult to interpret on its own. Some messages like Shipment and Vehicle have label properties to allow for easier matching of request and response data.

Route properties

Each routes[] entry is a ShipmentRoute message (REST, gRPC). Each ShipmentRoute represents the route assignment for a particular vehicle from the request. Important ShipmentRoute properties related to its corresponding Vehicle include:

• vehicleIndex is the zero-based index of the Vehicle in the corresponding request message. REST responses omit this property when the value is zero.
• vehicleStartTime is the time when the vehicle must begin its route.
• vehicleEndTime is the time when the vehicle is expected to finish its route.

In a response, routes will look like:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

Note: REST responses use Protocol Buffers' JSON representation, which omits fields that have their respective type's default value and that don't support field present. This means that integer properties like vehicleIndex are omitted when their values are zero. See also the official Protocol Buffers JSON Mapping Documentation.

Each ShipmentRoute includes an ordered list of visits that the vehicle will complete. Each Visit (REST, gRPC) represents a VisitRequest (REST, gRPC) from the corresponding request. Important Visit properties include:

• shipmentIndex is the zero-based index of the shipment this visit belongs to in the corresponding request.
• isPickup is true when a visit is a pickup and false when a visit is a delivery. REST responses omit this property when the value is false.
• visitRequestIndex is the zero-based index of the VisitRequest from Shipment.pickups or Shipment.deliveries in the corresponding request that the Visit represents. REST responses omit this property when the value is zero.
• startTime is the time the visit is expected to start.
• loadDemands maps load type to load amount demanded to complete the Visit. Load amounts are negative for delivery visits, representing load being removed from the vehicle.

An example Visit looks like:

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

Each ShipmentRoute includes an ordered list of transitions that represent travel between visits for a given vehicle. Important Transition message (REST, gRPC) properties include:

• startTime is the time at which the vehicle will start to perform the transition.
• travelDuration is the duration for which the vehicle must travel to complete the transition.
• travelDistanceMeters is the distance in meters that the vehicle must travel to complete the transition.
• trafficInfoUnavailable indicates whether traffic data is available for the transition.
• waitDuration represents idle time the vehicle spends waiting before it can start its next Visit. This may be incurred due to the start_time of the following Visit.
• totalDuration is the total duration of the transition, including travel, wait, break, and delay times.
• vehicleLoads maps load type to load amount carried by the vehicle during this transition.

An example Transition looks like:

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

For more information on the relationship between vists and transitions, see Pickup and Delivery Stop Order Optimization and the ShipmentRoute reference documentation (REST, gRPC). For more information on the routePolyline and routeToken properties of a Transition message, see Transition Polylines and Route Tokens.

Metrics properties

The Metrics message (REST, gRPC) summarizes the entire solution. Some important Metrics properties include:

• totalCost is the total cost incurred in completing the routes. Read more about costs in Cost Model Parameters.
• usedVehicleCount is the total number of vehicles used in the solution. Vehicles may have empty routes when the optimizer determines that their use is unnecessary.
• skippedMandatoryShipmentCount is the number of skipped shipments that are "mandatory." A mandatory shipment doesn't specify a penaltyCost that is incurred if the shipment is skipped. Mandatory shipments can still be skipped if their performance is not feasible under specified constraints. Read more about costs in Cost Model Parameters.

Additional metrics are reported as AggregatedMetrics messages (REST, gRPC). The AggregatedMetrics message type is used for the Metrics.aggregatedRouteMetrics property and for the ShipmentRoute.metrics property Metrics.aggregatedRouteMetrics contains metrics aggregated across all ShipmentRoutes in the OptimizeToursResponse. Each ShipmentRoute.metrics property contains metrics for that specific ShipmentRoute.

Important AggregatedMetrics properties include:

• performedShipmentCount is the number of shipments performed by vehicles over their entire routes.
• travelDuration is the total time the vehicles spend in transit while completing their routes.
• waitDuration is the total time the vehicles spend waiting while completing their routes.
• delayDuration is the total delay time for the vehicles. This is usually zero unless TransitionAttributes are used in the request.
• breakDuration is the total time the vehicles spend in breaks while completing their routes.
• visitDuration is the total time the vehicles spend performing visits while completing their routes. This is effectively the sum of all VisitRequest.duration values for VisitRequests corresponding to Visits assigned to applicable vehicle.
• totalDuration is the total duration required to complete the vehicles' routes.
• travelDistanceMeters is the total distance traveled by the vehicles while completing their routes.
• maxLoads maps load types to the maximum load amount carried by the vehicles at any point on their routes.

An example Metrics message looks like:

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

Important: if all costs are zero in the Metrics or ShipmentRoute messages, the optimizer is unlikely to have found an optimal order for Visit completion. At least one cost parameter must be specified, such as Vehicle.costPerKilometer or globalDurationCostPerHour, or else the optimizer may return any solution that satisfies specified constraints.

Complete example

A complete example response for the request from Construct a Request looks like:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}