Vehicle: Max Travel Cost and Max Tasks

In this example we will learn about some useful vehicle constraints. NextBillion.ai’s Route Optimization Flexible API provides options to control the maximum number of tasks that a vehicle can serve and also the maximum travel cost that it can incur. These parameters can be used to limit the usage of vehicles and prevent them against unexpected high costs, potential breakdowns or just control the fuel consumptions.

Get Started

Readers would need a valid NextBillion API key to try this example out. If you don’t have one, please contact us to get your API key now!

Setup

Once you have a valid API Key, you can start setting up the components to be used in this example. Let’s take a look at them below.

Jobs & Shipments

We start by defining 10 jobs and 3 shipments. For these tasks we add:

• A unique identifier for each task

• Location indexes for each task

• The schedule of tasks. This is done by adding time windows within which a task must be completed. We have added a 15 min time window for all tasks for the sake of simplicity, but Route Optimization Flexible API can handle complex task schedules as well.

• The actual time taken to complete the tasks once the driver/vehicle is at the task’s location i.e. the service time for each task.

• Pick-up and delivery quantities for shipments and jobs. Since we are adding capacities for the vehicles, we are adding quantities for jobs as pickup=[0]. Please refer to the Basic Route Optimization example to know more.

Let’s take a look at the jobs JSON after the above properties are configured:

1
{
2
  "jobs": "[...]"
3
}

Vehicles

Next, we add 4 vehicles that are going to fulfill the tasks within the defined constraints. To describe the vehicles and their properties we add:

• A unique ID for each vehicle

• Vehicle shift time or the time window

• Capacity to denote the amount of load that the vehicle can take

• Start_index to denote the point from where the vehicle would start.

• Costs for all vehicles. We have specified fixed cost for all vehicles and per_hourcost for two of the vehicles.

  • max_travel_cost to put a cap on the traveling cost that a vehicle can incur. We are going with 5000 seconds as the maximum cost per vehicle. Please observe that

  • cost here is in seconds, as we are not explicitly mentioning any travel_cost settings. Therefore, the solver goes with the default setting of duration for cost.

  • the max_travel_cost applies only to the “traveling” cost of the vehicle. Individual vehicle’s costs - per_hour or fixed - are outside the scope of this constraint. Therefore, the final cost may turn out to be more than that specified for max_travel_cost. We are covering such a case in this example. Please refer to Analyzing the Solution section.

• max_tasks to limit the number of tasks that each vehicle can take. We set this constraint to 5 tasks for each vehicle. It needs to be highlighted here that a job represents 1 task whereas a shipment represents 2 tasks (1 each for the pickup and the delivery step).

Once the vehicle and their properties are defined, the resulting vehicles JSON is:

1
{
2
  "vehicles": "[...]"
3
}

Locations

And lastly, we would define the locations object by adding all the locations used in the problem along with a valid id. The locations object with all the points used in this example:

1
{
2
  "locations": "{...}"
3
}

Optimization POST Request

Now let’s put all these components together and create the final POST request that we will submit to the optimizer.

1
curl --location 'https://api.nextbillion.io/optimization/v2?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

Optimization POST Response

Once the request is made, we get a unique ID in the API response:

1
{
2
"id": "96ba15bf2ef178053929bedd3b0f7d56",
3
"message": "Optimization job created",
4
"status": "Ok"
5
}

Optimization GET Request

We take the ID and use the Optimization GET request to retrieve the result. Here is the GET request:

1
curl --location 'https://api.nextbillion.io/optimization/v2/result?id=96ba15bf2ef178053929bedd3b0f7d56
2
&key=<your_api_key>'

Optimization GET Response

Following is the optimized route plan:

1
{
2
  "description": "Vehicle MaxTravelCost & MaxTask Example",
3
  "result": '{...}',
4
}

Following is a visual representation of the initial locations of tasks, vehicles and the routes suggested after optimization as per the given constraints.

Analyzing the Solution

Looking at the result we can observe some interesting insights:

• summary section:

  • We get an overview of the overall result with a total distance of 141270 meters covered within a total duration of 10502 seconds (~ 3 hrs) to complete all the assigned tasks.

  • Optimizer was able to assign all tasks using 4 routes with a total cost of 21899. This cost is in seconds as we did not explicitly specify any travel_cost, so the solver went with the default setting of duration.

  • Other fields in summary provide details about total service time of all the assigned tasks, total waiting_time for the assigned tasks among other details.

• routes section:

  • It can be observed that the max_tasks constraint for all vehicles has been successfully implemented in the solution - vehicle 1 is taking care of jobs 2, 4 and 5; vehicle 2 is assigned to shipment 1 and jobs 1,3 and 10; vehicle 3 is assigned to jobs 6, 7, 8 along with shipment 2; and lastly, vehicle 4 is assigned to job 9 and shipment 3.

  • In our example, the cost is calculated using the default metric - duration. Therefore, all costs in the solution are in seconds. Let’s take a look at the costs for each vehicle:

    • Vehicle 1: This vehicle was configured for both fixed and per_hour type of cost. When used, this vehicle incurs a cost of 1000 seconds along with additional 5400 seconds for every hour of operation. The total duration for which this vehicle operates is 794 seconds (~14 mins) and hence the per_hour cost for this vehicle comes out to be 1191 seconds. The total cost of the route, 2191 seconds, is then calculated by adding per_hour cost to the fixed cost of using the vehicle. Overall cost incurred for this vehicle is less than 5000 seconds, as specified by the max_travel_cost constraint.

    • Vehicle 2: This vehicle was configured for both fixed and per_hour type of cost. When used, this vehicle incurs a cost of 3000 seconds along with additional 3600 seconds for every hour of operation. The total duration for which this vehicle operates is 3989 seconds (~72 mins) and hence the per_hour cost for this vehicle comes out to be 3989 seconds. The total cost of the route, 6989 seconds, is then calculated by adding per_hour cost to the fixed cost of using the vehicle. It looks like that this vehicle did not adhere to the max_travel_cost constraint and incurred a total cost of more than 5000 seconds. But, it is important to note that max_travel_cost does not consider fixed cost in its calculations. The max_travel_cost applies to the travel_cost only, which in this case is the per_hour cost of 3989 seconds, which is well within the given cap of 5000 seconds.

    • Vehicle 3: This vehicle was configured for fixed cost considerations only. When used, this vehicle incurs a cost of 4000 seconds. The total duration that this vehicle operates for is 3548 seconds (~1 hr). The total cost for this vehicle is the sum of fixed cost and travel_cost, which comes out to be 7548 seconds. Similar to vehicle 2, the total cost for this vehicle also exceeds the given cap of 5000 seconds, but that can be attributed to the higher fixed cost. The travel_cost incurred is 3548 seconds only.

    • Vehicle 4: This vehicle was also configured for fixed cost considerations only. When used, this vehicle incurs a cost of 3000 seconds. The total duration that this vehicle operates for is 2171 seconds (~36 mins). The total cost for this vehicle is the sum of fixed cost and travel_cost, which comes out to be 5171 seconds. Similar to vehicle 2 and 3, the total cost for this vehicle also exceeds the given cap of 5000 seconds, but that can be attributed to the higher fixed cost. The travel_cost incurred is 2171 seconds only.

    • It is recommended to also refer to the Vehicle Costs example to understand more about cost calculations.

  • The total cost of solution, 21899 seconds, is arrived by adding up the costs of each individual route.

As demonstrated, NextBillion.ai’s Route Optimization Flexible API works within the provided constraints and suggests the best solution within those constraints. We encourage you to try out different configurations of vehicle or task locations, time window constraints, skills, number of tasks and explore how different routes, task distributions are returned when different scenarios are presented to Route Optimization Flexible API.

We hope this example was helpful. Check out some more use cases that Route Optimization Flexible API can handle for you!