Objectives

Objectives are parameters you can use to specify high-level optimization goals instead of providing specific cost parameters from the cost model.

You can use multiple objectives in a single request, and give each objective a relative weight to control how strongly it influences the overall optimization. Objectives affect your entire request, influencing all your vehicles and shipments. Lastly, you can also use objectives to start the development of your own cost model as described in Generate a cost model.

You can use objectives to control the following impacts on your route plan:

• Total travel time or distance of your routes.
• Total working time across all vehicles.
• Total number of vehicles used.

Properties

The objectives property is an array of Objective message types types within ShipmentModel. Each Objective defines a specific optimization goal and contains the fields listed in the following table:

Examples

This section covers two types of examples:

• A code sample that illustrates the structure of the objectives array.
• A request example that includes the objectives array.

Code samples

The following example shows the structure of objectives:

"objectives": [
  {
    "type": "OBJECTIVE_TYPE",
    "weight": WEIGHT
  }
]

Request example

The following example shows the structure of a basic optimizeTours request incorporating multiple objectives, where MIN_TRAVEL_TIME is 3 times as important as MIN_WORKING_TIME.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.42506261000996,
              "longitude": -122.09535511930135
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.42421503206021,
              "longitude": -122.09526063135228
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "travelMode": "DRIVING"
      }
    ],
    "objectives": [
      {
        "type": "MIN_TRAVEL_TIME",
        "weight": 3.0
      },
      {
        "type": "MIN_WORKING_TIME"
      }
    ]
  }
}

Generate a cost model

Objectives are a quick way to set optimization targets, but in some cases, they alone might not be specific enough. To achieve your exact routing goals, you may need the granular control only available through cost model parameters.

You can start the development of your own cost model by adding objectives to your request, then converting the objectives in your request to cost model parameters using the TRANSFORM_AND_RETURN_REQUEST solving mode.

When you send a request using this solving mode, the following happens:

• The API converts your objectives into cost model parameters and returns them in a processedRequest. You can then adjust the cost model parameters as needed to fine-tune your route plan.
• When using multiple objectives, the API combines the costs of all your objectives and scales them by their respective weights.
• You are not billed for this request, since the API doesn't provide you with an optimized route, it only converts the objectives to cost model parameters.

Example request

The following example shows a request using the MIN_TRAVEL_TIME objective and the TRANSFORM_AND_RETURN_REQUEST solving mode:

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.42506261000996,
              "longitude": -122.09535511930135
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.42421503206021,
              "longitude": -122.09526063135228
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "travelMode": "DRIVING"
      }
    ],
    "objectives": [
      {
        "type": "MIN_TRAVEL_TIME"
      }
    ]
  },
  "solvingMode": "TRANSFORM_AND_RETURN_REQUEST"
}

Example response

The following is the response corresponding to the previous request. This response includes both the generated cost model parameters and the original objective for reference.

{
  "processedRequest": {
    "model": {
      "shipments": [
        {
          "pickups": [
            {
              "arrivalLocation": {
                "latitude": 37.425062610009959,
                "longitude": -122.09535511930135
              }
            }
          ],
          "deliveries": [
            {
              "arrivalLocation": {
                "latitude": 37.424215032060211,
                "longitude": -122.09526063135228
              }
            }
          ]
        }
      ],
      "vehicles": [
        {
          "travelMode": "DRIVING",
          "costPerHour": 30,
          "costPerTraveledHour": 330,
          "costPerKilometer": 0.2
        }
      ],
      "objectives": [
        {
          "type": "MIN_TRAVEL_TIME"
        }
      ]
    },
    "solvingMode": "TRANSFORM_AND_RETURN_REQUEST"
  }
}