Vehicle Attributes & Order Matching

What are vehicle attributes?

Vehicle attributes are characteristics or qualities assigned to a vehicle, typically defined as custom key-value pairs. These attributes represent physical capabilities, features, or other operational aspects such as "driver_rating": “4.0”, "vehicle_type": "luxury_car", or "capacity": "2". Defining vehicle attributes allows the Driver Assignment service to make intelligent and relevant decisions when matching vehicles with orders.

Following is a sample vehicle with some attributes defined:

1
"vehicles": [
2
  {  
3
    "id": "Car 1",
4
    "attributes": {
5
      "vehicle_type": "luxury_car",
6
      "capacity": "4"
7
    },
8
    "location": {
9
      "lat": 34.0827,
10
      "lng": -118.3148
11
    }
12
  }
13
  ]

How attributes impact order fulfillment?

When creating an order, you can specify the desired vehicle characteristics using the vehicle_preference field. This field enables great control over which vehicles are eligible to fulfill a given order by specifying matching criteria across three preference types:

require_all_of_attributes: All attributes listed must be present in the vehicle. This behaves like an AND condition, ensuring only vehicles that match every listed attribute are considered.
require_any_of_attributes: At least one of the listed attributes must be present in the vehicle. This functions as an OR condition, allowing a broader match.
exclude_all_of_attributes: Vehicles with any of the listed attributes will be excluded. This is equivalent to a (NOT + AND) condition, filtering out vehicles that match even a single excluded attribute.

By combining these preferences, you can tailor the vehicle selection logic to fit specific operational requirements. The result is a precise and controlled matching process, ensuring orders are fulfilled only by vehicles that meet your exact criteria.

Following is a sample vehicle_preference field to filter and assign vehicles only with “driver_ratings” more than “4.0”.

1
"vehicle_preferences": {
2
      "required_all_of_attributes": [
3
        {
4
          "attribute": "driver_ratings",
5
          "operator": ">",
6
          "value": "4.0"
7
        }
8
      ]
9
    }

Example: API Request with Vehicle Preferences

The following request demonstrates how to use vehicle attributes and preferences to fulfill available orders. We will define three orders, each with distinct matching criteria:

Order 1 requires a vehicle with more than 2 seats.
Order 2 allows vehicles that either have more than 3.0 driver rating or at least 5 seats.
Order 3 excludes any vehicle with a driver rating below 4.

Three vehicles are also included, each with different combinations of driver_rating and seats attributes. The pickup_eta filter is set to 600 seconds (10 minutes), limiting results to vehicles that can reach the pickup point within that time. The JSON request format includes both orders and vehicles, specifying their locations and attribute-based constraints to guide the matching logic.

Sample Request

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
}

We can see that the API returns a structured response indicating which orders were assigned to which vehicles, along with details on unmatched orders and available vehicles. In this case:

Order 1 is assigned to Car 1, which satisfies the requirement of having more than 2 seats.
Order 3 is matched with Car 2, as its attributes pass the exclusion filter (driver rating is exactly 4, not below 4).
Order 2 remains unassigned because no vehicle met at least one of its required preferences—either a driver rating less than 3.0 or at least 5 seats.

Each assigned trip includes pickup details such as distance and ETA from the vehicle’s current location. The available_vehicles list also includes Car 3, which remained un-assigned.

Assignment Logic and Matching Workflow

Once the API received the request, it evaluated each vehicle-order pairing against the specified attribute constraints. The matching process followed a two-step approach:

Filtering by ETA: Vehicles were first filtered based on whether they could reach the pickup location within the pickup_eta threshold (600 seconds in this case). This step identifies the set of candidate vehicles for each order.
Attribute-Based Matching: For each eligible candidate vehicle, the API checked whether the vehicle's attributes satisfied the preferences configured for each of the orders as described above.

This matching logic ensures that business rules encoded via vehicle_preferences are strictly enforced during real-time dispatch. Vehicles that do not meet the constraints are excluded from consideration, and orders without valid matches are explicitly listed with the reason.

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