Prioritized Assignments

What are prioritized Assignments?

When planning routes, not all orders and vehicles carry the same weight. Some deliveries are more time-sensitive, some customers are more critical, and some vehicles are better suited to handle specific types of work.

To account for these differences, the Driver Assignment API allows you to assign priority scores to both orders and vehicles. These scores influence how assignments are made by tilting the balance in favor of higher-priority orders and vehicles while still respecting overall efficiency. Users also have a choice to define the priority scores explicitly or derive them automatically using rule-based priority mappings for eligible orders and vehicles.

Priority based orders and vehicle assignments are particularly useful in industries like ride-hailing, last-mile delivery, and field services, where certain jobs or vehicles must be favored without compromising the bigger operational picture.

How to prioritize assignments for orders and vehicles?

You can prioritize orders and vehicles by directly setting their priority field or by defining attribute-based priority assignment rules. Orders or vehicles meeting the criteria of a priority assignment rule will be assigned the priority score specified by that rule. To set up attribute-based priority mappings, use order_attribute_priority_mappings and vehicle_attribute_priority_mappings under options .

When an order or vehicle meets the criteria for multiple priority assignment rules, the highest priority value is applied. If direct priorities are set using the priority field, any priority scores generated from attribute-based assignment rules for that specific order or vehicle are ignored.

Example: API Request with prioritized orders and vehicles

To illustrate how prioritized orders and vehicles work in practice, let’s consider a ride-hailing scenario where both riders (orders) and drivers (vehicles) have varying levels of importance. In the following example, certain customers are tagged as “premium” and should be favored when assignments are made, while others fall under the “normal" category. On the driver side, vehicles supporting premium trip types or drivers with higher ratings should be prioritized over others. We use both explicit as well as rule-based priority configurations to assign respective priorities for required orders and vehicles.

Additionally, the service must balance these preferences against real-world constraints such as location, ETA, and travel distance.

Sample Request

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

Sample Response

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

Looking at the output reveals several important insights:

  1. Priority Orders vs. Normal Orders:

    • Premium orders such as Pickup 3 were assigned earlier despite having a longer travel distance, because their higher effective order priority (3) outweighed that of nearby normal orders.

    • Pickup 1, though premium, was left unassigned due to travel cost constraints, showing that priorities cannot override feasibility.

  2. Vehicle Priorities Matter:

    • v1 (premium trip type, priority 4) was assigned to a premium customer (Pickup 3), even though the ETA was higher compared to other options.

    • v4 (driver rating 4.5, effective vehicle priority 3) handled Pickup 2, a normal order, because its location allowed a quicker ETA.

  3. Explicit vs. Rule-based Priority:

    • Pickup 4 had an explicitly set priority of 1, which overrode the rule-based premium order priority (3). We can conclude that the explicit priorities take precedence when specified. This behavior allows operators to override any rule-based priorities for a given order.

    • Similarly, v3 had an explicit priority of 1, which reduced its influence compared to its natural attributes (premium trip + high rating).

  4. Balancing Priority and Efficiency:

    • Pickup 5 (a normal order) still got assigned to v2 because of proximity and lower ETA, emphasizing that while the optimizer tilts toward higher-priority entities, it still seeks overall efficiency.

Assignment Logic and Workflow

In presence of prioritized orders and vehicles, the service performs following operations at a high-level:

  1. Evaluate Orders: Orders were scanned for explicit priorities first. Where none were set, rule-based mappings applied automatically.

  2. Evaluate Vehicles: Each vehicle’s attributes were mapped into priorities. Premium-enabled vehicles like v1 were ranked higher (priority 4), while normal vehicles like v2 ranked lower. Explicit priorities, when present (e.g., v3), superseded rule-based values.

  3. Matching Process: The optimizer weighed order priorities against vehicle priorities alongside location and ETA. For example:

    • Pickup 3 (priority 3) → matched with v1 (priority 4) despite a long ETA.

    • Pickup 2 (priority 1) → matched with v4 (priority 3) because of proximity.

    • Pickup 5 → matched with v2 purely for travel efficiency, despite being low priority.

  4. Constraint Handling: Orders like Pickup 1 were excluded due to relatively infeasible travel costs, ensuring that the assignments remain realistic.

This workflow highlights that priority scoring is not an absolute override but a weighted input — helping steer assignments toward higher-value outcomes without breaking real-world constraints.

Check out other advanced features of the Driver Assignment API to achieve rapid and efficient on-demand order fulfillment.