Driver Assignment API

Introduction

The Driver Assignment API assigns best available drivers to open tasks based on specific constraints. It helps optimize the resource allocation in real-time, ensuring efficient service to ride-hailing passengers and any other service appointments.

Key Features

• Smart Order-to-Driver Matching: Assign drivers intelligently based on task requirements, vehicle specifications, and other custom business rules.
• Flexible Cost Models: Optimize driver assignments with multiple cost options - time-based, distance-based, or straight-line calculations.
• Advanced Filtering: Refine driver selection with distance and duration constraints to ensure optimal efficiency.
• Back-to-back orders: Allow drivers to efficiently complete consecutive trips without delays.
• Alternate Assignments: Automatically suggests backup drivers for each order to ensure service continuity.
• Prioritized Assignments: Allows ranking orders and vehicles by priority so that high-value orders and preferred vehicles are matched first.

The Driver Assignment API offers both synchronous and asynchronous methods for requesting optimal driver assignments. Let’s look at each method in detail.

Synchronous Driver Assignment Method

Create a request

The Driver Assignment API’s synchronous method caters to quick, near real-time assignment requirements like in case of ride hailing applications. It is best suited for situations when drivers and orders are spread in a relatively smaller area. The service requires the pickup and drop off locations of the orders and the details of available vehicles to fulfill the orders. A vehicle with an ongoing trip can also be configured by specifying the waypoints remaining on the current trip. The distance or duration based filters and custom vehicle preferences for each order can also be configured to establish rules identifying the most favoured vehicle for fulfilling each order.

Request Parameters

Request Body

Response Schema

The Driver Assignment API response includes the details of assignments along with the sequence in which the ongoing steps and pickups can be completed. The orders which remained unassigned and the vehicles which were not assigned to any orders are also returned. The complete details of a trip along with drop off steps can be accessed by setting the dropoff_details parameter to true in the input request.

Synchronous Driver Assignment API Example

Sample Request

1
curl --location 'https://api.nextbillion.io/optimization/driver-assignment/v1?key=<your_api_key>' --header 'Content-Type: application/json; charset=utf-8' --data '{
2
  "filter": {...},
3
  "options": {...},
4
  "orders": [...],
5
  "vehicles": [...]
6
}'

Sample Response

1
{
2
 "status": 200,
3
 "result": {
4
     "trips": [...],  
5
     "unassigned_orders": [...],
6
     "available_vehicles": [...],
7
 }
8
}

Asynchronous Driver Assignment Method

The Asynchronous version Driver Assignment API returns a unique solution ID upon submitting a valid input request. The solution ID can then be used to retrieve the assignment solution anytime. The async method also offers enhanced filter limits for searching and matching orders to available drivers spread over a large region. Use the GET method to retrieve the solution. All the details are covered in the following sections.

Submit a request

Use the following endpoint to submit an asynchronous driver assignment request

Request Parameters

Request Body

Response Schema

Retrieve a solution

To obtain the calculated assignment solution, you must provide the specific id that was generated and returned after submitting the initial POST request. Access the solution using the following endpoint:

Request Parameters

Response Schema

Asynchronous Driver Assignment API Example

Here is a sample input problem that we submit using the POST endpoint for asynchronous method.

1
curl --location 'https://api.nextbillion.io/optimization/driver-assignment/v1/async?key=<your_api_key>' --header 'Content-Type: application/json; charset=utf-8' --data '{
2
  "filter": {...},
3
  "options": {...},
4
  "orders": [...],
5
  "vehicles": [...]
6
}'

Once the input request is successfully submitted, we get the following sample response containing the unique ID for the solution:

1
{
2
    "id": "9a3226f7-aa0f-422f-afaf-3639a3cc7b29",
3
    "status": "200",
4
    "message": "Driver Assignment request created successfully",
5
    "warning": []
6
}

We then use the GET endpoint of to access the calculated solution

1
curl --location 'https://api.nextbillion.io/optimization/driver-assignment/v1/result?id=9a3226f7-aa0f-422f-afaf-3639a3cc7b29&key=<your_api_key>'

API Rate Limits and Usage Restrictions

1. Nextbillion.ai allows a maximum rate limit of 300 queries per minute or 5 queries/second for continuous requests.

   Note: We can increase the quota if needed on request. Contact support@nextbillion.ai for more details.

2. For synchronous method,

   1. maximum filter.radius allowed is 10,000 meters.
   2. maximum filter.pickup_eta allowed is 3600 seconds.
   3. maximum filter.driving_distance allowed is 10,000 meters.

3. For asynchronous method,

   1. maximum filter.radius allowed is 200,000 meters (200kms).
   2. maximum filter.pickup_eta allowed is 28,800 seconds (8hrs).
   3. maximum filter.driving_distance allowed is 700,000 meters (700kms).

4. The maximum number of orders that can be added in a single request is 200.

5. The maximum number of vehicles that can be specified in a single request is 100.

6. The maximum number of remaining_waypoints that can be added for a vehicle is 10.

7. The maximum number of attributes that can be specified for a single vehicle is 30.

8. A maximum of 10 attribute conditions can be specified under each of required_all_of_attributes, required_any_of_attributes and exclude_all_of_attributes for an order.

API Error Handling