Multi-Destination Trips

What are multi-destination trips?

A multi-destination trip involves serving multiple drop-off points within a single route. In ride-hailing scenarios, this typically means picking up multiple riders from a common location and dropping them off at their individual destinations. In delivery use cases—such as food or parcel delivery—the same principle applies: one pickup, followed by multiple unique drop-offs. This setup allows for better utilization of vehicle capacity and improved efficiency in urban logistics or pooled transport services.

How to define multiple destinations for a trip?

To define multiple destinations within a trip, the dropoffs field should be used when configuring orders with a common pickup location. The destinations must be listed in the intended sequence of drop-off, as the Driver Assignment API does not reorder or optimize this sequence automatically.

To receive detailed routing insights, enable the dropoff_details option. This ensures the API response includes granular step-by-step information—such as ETA and distance—for each leg of the journey, helping track and manage complex multi-stop workflows.

Example: API Request with Multi-Destination Configuration

Below is a sample request to create multi-destination trips. Two orders are configured, both originating from a given pickup location but having distinct drop-off points. The request uses the dropoffs field to define the destination sequence for each order.

Additionally, the dropoff_details option is enabled to retrieve per-stop routing details such as distance and ETA in the response. Each order also includes vehicle attribute preferences to control assignment eligibility.

Sample Request Payload

1
curl --location 'https://api.nextbillion.io/optimization/driver-assignment/v1?key=<you_api_key>' --header 'Content-Type: application/json' --data '{
2
 "filter": {...},
3
 "orders": {...},
4
 "vehicles": {...}
5
}

Sample Response

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

The response provides detailed trip assignments, including the sequence of steps for each vehicle. Since dropoff_details was enabled in the request, the API returns step-by-step routing information, including distances and estimated times for pickups, intermediate waypoints, and drop-offs.

• Order 1 is assigned to Car 1, which follows a multi-stop route:
  1. Pickup at the shared origin.
  2. Intermediate waypoint (first drop-off location).
  3. Final drop-off (second drop-off location).
• Order 2 is assigned to Car 2, following a straightforward two-step trip:
  1. Pickup at the shared origin.
  2. Direct drop-off at the specified destination.

Each trip includes distance and ETA details for each step. The response also indicates that all orders were successfully assigned, as unassigned_orders is “null”, and no additional available vehicles remain unallocated.

Assignment and Route Construction Workflow

Upon receiving the request, the system performed the following operations:

1. Filtering by ETA:

Vehicles were first filtered based on their ability to reach a given pickup location within the specified pickup_eta of 900 seconds (15 mins).

2 .Route Construction: Once the qualifying vehicles were identified based on the given attributes, the system:

• Created multi-stop routes using the dropoffs field as provided (no sequence optimization was performed).
• Included intermediate waypoints for orders with more than one drop-off.
• Calculated distance and ETA for each leg of the journey to generate detailed trip steps.

Check out all the advanced features of Driver Assignment API and learn how to leverage them for fast, efficient on-demand order fulfillment.