Extend agent shift timings

Product Used: Route Optimization API

NextBillion.ai’s Route Optimization API provides users with a high degree of customization by leveraging over 50+ parameters to closely emulate the real-world constraints of route planning. One of the features is “max_vehicle_lateness” which allows the agents to operate for a specified amount of additional time beyond their shift timings. Leverage this additional time to fulfill additional tasks at the cost of a known penalty.

In this example, we have 1 operator who is allowed to work for additional 30 mins beyond the usual shift timings if it makes him fulfill more tasks by utilizing the additional time.

Configure optimization request

To configure a Route Optimization request we will need to set up the locations, tasks, vehicles and the constraints involved in our use case. Let’s address them one by one below.


We configure the locations attribute and add all the locations used in the problem along with a valid id. We add locations for 5 tasks and the starting point of the agent. Following is the locations object with all the coordinates to be used in this example:

1"locations": {
2 "id": 1,
3 "location": ["34.06675919,-118.30620984", "34.04268850,-118.28191077", "34.03434239,-118.28358834", "34.04238041,-118.23817754", "34.08431954,-118.25597762", "34.06892275,-118.29156827"]
4 }


We define 5 tasks that need to be performed in this example. Following are the constraints that we set for these tasks:

  • A unique id for each task
  • location_index for each task
  • time_windows to specify the duration within which the task has to be completed
  • Time taken to complete the task once the agent is at the task’s location i.e. the “service” time for each task.

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

1"jobs": "[...]"


Next, we add details about the agent that is responsible for fulfilling the above tasks. For the agent, we add:

  • A unique ID
  • “start_index” to denote the point from where the agent starts.
  • “time_window” to indicate the usual shift timings of the agent

Following is the vehicles JSON with all the above properties configured:

1"vehicles": "[...]"


Next, we add the configuration to allow the agent to extend his shift by 30 mins if needed to fulfill additional tasks. We use the max_vehicle_overtime property under “options” to do so

2 "constraint":{
3 "max_vehicle_overtime":1800
4 }
5 }

Route Optimization POST request

All the above components are now combined and submitted as a single JSON to the Route Optimization endpoint:

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

Route Optimization POST request

Once the above POST request is successfully submitted, a response similar to the following is received:

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

Retrieve optimization solution

Capture the task “id” from the POST response and use it in a subsequent GET request to retrieve the optimized solution asynchronously:

Route Optimization GET request

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

Route Optimization GET response

In the response, we see that the optimizer has assigned all the tasks and there are no unassigned tasks. We also see that the “Job 5” which was scheduled outside the usual shift timings of the agent is also fulfilled as the agent was allowed to extend his shift time by 30 mins, if needed. In the response we can see that “vehicle_overtime” field returns the amount of additional duration that the agent worked for, to complete this task.

2 "description": "Shift Timings",
3 "result": {
4 "code": 0,
5 "summary": "{...}",
6 "routes": "[....]"
7 }

Visit Route Optimization Flexible API documentations to know more about the available optimization features.