Routing with Vehicles

It is possible to specify vehicle objects with your request and have the optimizer assign these to routes, to constrain the jobs that a route can service. Vehicles can also be explicitly assigned to routes in a request, or selected as a preferred vehicle for drivers in a request.

Note

To run the examples in this tutorial, you will need:

A RouteCloud API login. Use your Verizon Connect Enterprise username and password to authenticate with the RouteCloud API. To obtain a username and password, contact Verizon Connect sales.
cURL to run the requests. You can download a cURL binary from here.

The enable_explicit_vehicles Flag

The settings.enable_explicit_vehicles flag can be used to determine if a request is expected to contain vehicle objects.

It is unnecessary to provide this flag in the following cases:

The request already contains vehicle objects (in this case, the default value is true and setting it to false is invalid).
The request contains one or more routes with inline vehicle fields (in this case, the default value is false and setting it to true is invalid).

If there are no vehicle objects and no routes containing inline vehicle fields, the flag defaults to false.

If the flag is set to true while there are no vehicles in the request, each route will have a route_has_no_vehicle violation applied to it.
If the flag is false, vehicle assignment will not occur and no violations relating to vehicles will be applied.

Assigning Vehicles in a Build Request

If a route is provided in a build_request with no route.vehicle, the optimizer attempts to assign a suitable vehicle from the request to it. This does not occur if the enable_explicit_vehicles flag is false.

If the route specifies a driver who has a preferred vehicle, this vehicle is assigned to the route in all cases. Otherwise, the optimizer selects the optimal vehicle for the route, provided the route is not empty.

Request

{
  "routes": [
    { "id": "route0", "location": "39.718005, -104.969531" }
  ],
  "jobs": [
    { "id": "job0", "location": "39.635928, -105.049219" }
  ],
  "vehicles": [
    { "id": "vehicle0", "location": "39.718005, -104.969531" }
  ]
}

The routing_with_vehicles_build.json build_request. Download it here. Click here to open it in the UI.

The request defines:

One route, route0, with no vehicle.
One job, job0, to be assigned to route0 so that it is not empty.
One vehicle, vehicle0, with the same location as the route's.

The way the vehicle assignment action is represented depends on the value of the return_request field, described in the following section.

Response without return_request

{
  "routes": [
    {
      "id": "route0", ...
      "stops": [...],
      "vehicle": "vehicle0"
    }
  ],
  "unrouted_jobs": []
}

A snipped version of the routing_with_vehicles_build.json response. The full response is available here. Click here to open it in the UI.

The vehicle field of the route response has been set to vehicle0, the id of the vehicle provided in the request.

The same request with the return_request field set to true can be downloaded here.

Response with return_request

{
  "jobs": [
    { "id": "job0", "location": "39.635928, -105.049219" }
  ],
  "routes": [
    { 
      "id": "route0",
      "location": "39.718005, -104.969531",
      "response": { ... },
      "stops": [ ... ],
      "optimizer_assigned_vehicle": "vehicle0"
    }
  ],
  "vehicles": [
    { "id": "vehicle0", "location": "39.718005, -104.969531" }
  ],
  "return_request": true
}

A snipped version of the routing_with_vehicles_return_request.json response. The full response is available here. Click here to open it in the UI.

In this case, the optimizer_assigned_vehicle field of the route has been set to vehicle0, the id of the vehicle.

The vehicle field is never assigned by the optimizer, allowing for subsequent builds using the returned request to carry out vehicle assignment again. optimizer_assigned_vehicle is accepted as the vehicle for the route in all request types except for build_request, where it is ignored. This means that the vehicle assigned by the build will be used for optimization in subsequent insert, resequence, recommend, and evaluate requests, unless a different vehicle is provided in the vehicle field.

Violations

If the optimizer is unable to assign a vehicle to a route for any reason, the route receives a route_has_no_vehicle violation.
If a route specifies a different vehicle to its driver's preferred vehicle, it receives a driver_not_using_preferred_vehicle violation.
If a route starts or ends at a different location to its assigned vehicle's location or depot, it receieves a vehicle_depot_different_to_route_start_location or vehicle_depot_different_to_route_end_location violation, respectively.

A route does not receive any of these violations if there are no vehicle objects provided in the request.