# 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 ```bash curl --location 'https://api.nextbillion.io/optimization/driver-assignment/v1?key=' \ --header 'Content-Type: application/json' \ --data '{ "filter": { "pickup_eta": 900 }, "options": { "dropoff_details": true }, "orders": [ { "id": "Order 1", "pickup": { "lat": 34.05193613, "lng": -118.30837249 }, "dropoffs": [ { "lat": 34.07087471, "lng": -118.30336152 }, { "lat": 34.06365379, "lng": -118.29785936 } ], "vehicle_preferences": { "required_all_of_attributes": [ { "attribute": "seats", "operator": ">", "value": "3" } ] } }, { "id": "Order 2", "pickup": { "lat": 34.06204181, "lng": -118.32421491 }, "dropoffs": [ { "lat": 34.07219683, "lng": -118.29798829 } ], "vehicle_preferences": { "exclude_all_of_attributes": [ { "attribute": "driver_rating", "operator": "<", "value": "4" } ] } } ], "vehicles": [ { "id": "Car 1", "attributes": { "driver_rating": "5.0", "seats": "4" }, "location": { "lat": 34.08276781, "lng": -118.31481656 } }, { "id": "Car 2", "attributes": { "driver_rating": "4.0", "seats": "4" }, "location": { "lat": 34.07255780, "lng": -118.32192368 } } ] }' ``` ### Sample Response ```json { "status": 200, "result": { "trips": [ { "trip_id": "8452f9c0-2049-4e18-a369-fdea94af8c23", "vehicle": { "id": "Car 1", "steps": [ { "type": "pickup", "order_id": "Order 1", "location": { "lat": 34.05193613, "lng": -118.30837249 }, "distance": 4471, "eta": 627 }, { "type": "intermediate_waypoint", "order_id": "Order 1", "location": { "lat": 34.07087471, "lng": -118.30336152 }, "distance": 2750, "eta": 380 }, { "type": "dropoff", "order_id": "Order 1", "location": { "lat": 34.06365379, "lng": -118.29785936 }, "distance": 1335, "eta": 238 } ], "vehicle_current_location": { "lat": 34.08276781, "lng": -118.31481656 } } }, { "trip_id": "27559155-c56b-41c6-8007-cf73d852c201", "vehicle": { "id": "Car 2", "steps": [ { "type": "pickup", "order_id": "Order 2", "location": { "lat": 34.06204181, "lng": -118.32421491 }, "distance": 1332, "eta": 230 }, { "type": "dropoff", "order_id": "Order 2", "location": { "lat": 34.07219683, "lng": -118.29798829 }, "distance": 3673, "eta": 491 } ], "vehicle_current_location": { "lat": 34.0725578, "lng": -118.32192368 } } } ], "unassigned_orders": null, "available_vehicles": null } } ``` 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](https://docs.nextbillion.ai/optimization/driver-assignment-api/examples) and learn how to leverage them for fast, efficient on-demand order fulfillment.