Re-Optimization: Unassigned Tasks’s Route Optimization Flexible API offers a powerful re-optimization feature which allows the users to fulfill previously unassigned tasks by readjusting some variables. These variables can be the number of vehicles included in the optimization request, modifying the shift timings or capacities of the vehicles involved or changing the task time windows or any other strategy that would increase the chances of higher task assignments.

Re-optimization works based on a previous solution which had some unassigned tasks. The users are expected to rebuild the request using some of the above strategies and specify the unassigned tasks explicitly. Upon receiving a re-optimization request, the solver will try to accommodate the new tasks into the original solution without many changes. This way businesses can make quick or last-minute adjustments to their route planning without needing to make extravagant changes to the existing plans.

We cover this example through 2 steps - in the first step, we intentionally configure some tasks so that they remain unassigned in the original solution. In the next step, using the unassigned attribute, we re-optimize our existing solution so that all tasks are assigned. Let’s start with building the original request.

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!


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 5 jobs and 2 shipments. For these tasks we add:

  • A unique identifier for each task

  • Location indexes for each task

  • Specify 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.

  • 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.

  • Skills needed to perform each task

  • Pickup and Delivery amounts for all jobs

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

2 "jobs": "[...]",
3 "shipments": "[...]"


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. We have kept this same for both vehicles in the first step.

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

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

  • Skills for all vehicles

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

2 "vehicles": "[...]"


Next, we define the locations object and add all the locations used in the problem along with a valid id. The locations object with all the points used in this example:

2 "locations": "{...}"

Step 1: Get the original Solution

Now that we have built the basic components of an optimization problem with one shipment deliberately scheduled outside the vehicle’s shift timings so that it remains unassigned, we can submit this request using the Optimization POST method and retrieve the solution.

Optimized POST request

1curl --location '<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

Optimized POST response

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

2"id": "68b637d43438d84ae2fcd8ea3be063b6",
3"message": "Optimization job created",
4"status": "Ok"

Optimized GET request

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

1curl --location '

Let's take a look at the summary and the unassigned section of the original solution.

2 "result": {
3 "code": 0,
4 "summary": "{...}"
5 }
6 }

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


Step 2: Prepare for re-optimization

In the summary section of the original response, we can see that there was 1 unassigned task and the unassigned attribute gives the details of the unassigned shipment. Readers are encouraged to observe the routes and task distribution as well in this solution.

As a business operator it might be in our interest to keep the unassigned tasks to a minimum. In order to do that, we now reconfigure our input request so that the unassigned task gets assigned. To achieve this we first need to understand why some jobs or shipments remain unassigned. In our example, we know it is because the shipment was scheduled outside the shift timings of both vehicles.

We add the details of the unassigned shipment to the unassigned section of the input request. Next, we modify the shift timings of vehicle 2 so that it covers the time window of the unassigned shipment pickup and delivery steps and makes the task assignment feasible. We chose vehicle 2 for this modification because, in the original solution, it didn't start until almost 4 hours into its shift.

Vehicles for re-optimization

After updating the vehicle 2 shift timings, the updated vehicles JSON is:

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


Finally, we add the details of the unassigned shipment as per the original solution to the input request.

1"unassigned": {
2"shipment": [[2,2]]

Optimization POST Request

Now let’s put all these components together and create the final POST request that we will submit to the optimizer. Please ensure to add the new vehicle attributes, reflecting the updated shift timings, instead of the original object. Following is the final re-optimization request.

1curl --location '<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:

2"id": "151f2e007b0774958e837ec8dcacfc9c",
3"message": "Optimization job created",
4"status": "Ok"

Optimization GET Request

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

1curl --location '

Optimization GET Response

Following is the optimized route plan:

2 "description": "Re-optimization (new-tasks) Example",
3 "result": "{...}"

Following is a visual representation of all the task locations, location of vehicles and the routes suggested after re-optimization as per the given constraints.


Analyzing the Solution

Looking at the new result we can observe some interesting insights:

  • All the tasks are assigned within the same 2 routes.

  • The task distribution, sequence, costs, waiting times for vehicle 1 is almost the same as the original solution.

  • For vehicle 2, apart from the newly assigned shipment 2 steps, all properties for other tasks it had originally - like sequence of assigned tasks, wait times for those tasks, costs, arrival times etc - remain more or less similar.

  • The previously unassigned shipment is now fulfilled by vehicle 2, as the new shift timings make it possible.

  • The optimizer has proficiently added two more steps (the originally unassigned shipment steps) to the new solution, without making many changes to the original solution's existing parameters.

Above example showcases the powerful re-optimization capabilities of’s Route Optimization Flexible API. Users can leverage this feature to make last minute adjustments to their optimization plans to improve overall task fulfillment. To explore this feature more, users can play around with strategies like adding more vehicles, changing the task time window and see how the API takes those changes into account without major changes to the original solution.

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