--- title: "Assign Drivers to Orders" method: POST path: "/optimization/driver-assignment/v1" tags: ["Optimization"] --- # Assign Drivers to Orders `POST /optimization/driver-assignment/v1` Assigns available drivers (vehicles) to open orders based on specified criteria and constraints. ## Query parameters - `key` string, 32 character alphanumeric string, required ## Request body - object - `orders` Order[], required — Collects the details of open orders to be fulfilled. Each object represents one order. All requests must include orders as a mandatory input. A maximum of 200 orders is allowed per request. - `id` string, required — Specify a unique ID for the order. - `pickup` object, required — Specify the location coordinates of the pickup location of the order. This input is mandatory for each order. - `lat` number — Latitude of the pickup location. - `lng` number — Longitude of the pickup location. - `dropoffs` object[] — Use this parameter to specify the location coordinates of the destination of the trip or the intermediate stops to be completed before it. Please note * The last location provided is treated as the destination of the trip. * dropoffs is mandatory when dropoff_details is set to **true**. - `lat` number — Latitude of the stop location. - `lng` number — Longitude of the stop location. - `service_time` integer — Specify the service time, in seconds, for the order. Service time is the duration that the driver is likely to wait at the pickup location after arriving. The impact of the service time is realized in the ETA for the "dropoff" type step. - `vehicle_preferences` object — Define custom preferences for task assignment based on vehicle's attributes. If multiple criteria are provided, they are evaluated using an AND condition—meaning all specified criteria must be met individually for a vehicle to be considered. For example, if required_all_of_attributes, required_any_of_attributes, and exclude_all_of_attributes are all provided, an eligible vehicle must satisfy the following to be considered for assignments: 1. Meet all conditions specified in required_all_of_attributes. 2. Meet at least one of the conditions listed in required_any_of_attributes. 3. Not meet any conditions mentioned in exclude_all_of_attributes. Consequently, a vehicle which does not have any attributes defined can't be assigned to an order which has vehicle_preferences configured. - `required_all_of_attributes` object[] — An array of objects to add mandatory requirements for the order. A vehicle must **meet** **all conditions** specified here to be considered for assignment. Each object represents a single condition. Please note that a maximum of 10 conditions can be added here for a given order. - `attribute` string, required — Specify the name of the attribute. The attribute is compared to the keys (of each key:value pair) in vehicles.attributes during evaluation. - `value` string, required — Specify the desired value of the attribute to be applied for this order. value provided here is compared to the values (of each key:value pair) in vehicles.attributes during evaluation. - `operator` string, required — Specify the operator to denote the relation between attribute and the value specified above. The attribute , operator and value together constitute the condition that a vehicle must meet to be eligible for assignment. Currently, we support following operators currently: * Equal to (==) * Less than (<) * Less tha equal to (<=) * Greater than (>) * Greater than equal to (>=) * Contains (contains) Please note that when using "contains" operator only one value can be specified and the corresponding attribute must contain multiple values when defined for a vehicle. - `required_any_of_attributes` object[] — An array of objects to add optional requirements for the order. A vehicle must **meet** **at least one of the conditions** specified here to be considered for assignment. Each object represents a single condition. Please note that a maximum of 10 conditions can be added here for a given order. - `attribute` string, required — Specify the name of the attribute. The attribute is compared to the keys (of each key:value pair) in vehicles.attributes during evaluation. - `value` string, required — Specify the desired value of the attribute to be applied for this order. value provided here is compared to the values (of each key:value pair) in vehicles.attributes during evaluation. - `operator` string, required — Specify the operator to denote the relation between attribute and the value specified above. The attribute , operator and value together constitute the condition that a vehicle must meet to be eligible for assignment. Currently, we support following operators currently: * Equal to (==) * Less than (<) * Less tha equal to (<=) * Greater than (>) * Greater than equal to (>=) * Contains (contains) Please note that when using "contains" operator only one value can be specified and the corresponding attribute must contain multiple values when defined for a vehicle. - `exclude_all_of_attributes` object[] — An array of objects to add exclusion requirements for the order. A vehicle must **not meet any of the conditions** specified here to be considered for assignment. Each object represents a single condition. Please note that a maximum of 10 conditions can be added here for a given order. - `attribute` string, required — Specify the name of the attribute. The attribute is compared to the keys (of each key:value pair) in vehicles.attributes during evaluation. - `value` string, required — Specify the desired value of the attribute to be applied for this order. value provided here is compared to the values (of each key:value pair) in vehicles.attributes during evaluation. - `operator` string, required — Specify the operator to denote the relation between attribute and the value specified above. The attribute , operator and value together constitute the condition that a vehicle must meet to be eligible for assignment. Currently, we support following operators currently: * Equal to (==) * Less than (<) * Less tha equal to (<=) * Greater than (>) * Greater than equal to (>=) * Contains (contains) Please note that when using "contains" operator only one value can be specified and the corresponding attribute must contain multiple values when defined for a vehicle. - `priority` integer — Specify the priority for this order. A higher value indicates a higher priority. When specified, it will override any priority score deduced from order_attribute_priority_mappings for this order. Valid values are \[1, 10\] and default is 0. - `attributes` object — Specify custom attributes for the orders. Each attribute should be created as a key:value pair. The **keys** provided can be used in options.order_attribute_priority_mappings to assign a custom priority for this order based on its attributes. The maximum number of key:value pairs that can be specified under attributes for a given order, is limited to 30. - `vehicles` Vehicle[], required — Collects the details of vehicles available to fulfill the orders. Each object represents one vehicle. All requests must include vehicles as a mandatory input. A maximum of 100 vehicles is allowed per request. - `id` string, required — Specify a unique ID for the vehicle. - `location` Location, required — Location info. - `lat` number, required — Latitude of location. - `lon` number, required — Longitude of location. - `attributes` object — Specify custom attributes for the vehicle. Each attribute should be created as a key:value pair. These attributes can be used in the orders.vehicle_preferences input to refine the search of vehicles for each order. The maximum number of key:value pairs that can be specified under attributes for a given vehicle, is limited to 30. - `remaining_waypoints` Location[] — An array of objects to collect the location coordinates of the stops remaining on an ongoing trip of the vehicle. The service can assign new orders to the vehicle if they are cost-effective. Once a new order is assigned, the vehicle must complete all the steps in the ongoing trip before proceeding to pickup the newly assigned order. Please note that a maximum of 10 waypoints can be specified for a given vehicle. - `lat` number, required — Latitude of location. - `lon` number, required — Longitude of location. - `priority` integer — Specify the priority for this vehicle. A higher value indicates a higher priority. When specified, it will override any priority score deduced from vehicle_attribute_priority_mappings for this vehicle. Valid values are \[1, 10\] and default is 0. - `filter` object, required — Specify the filtering criterion for the vehicles with respect to each order's location. filter is a mandatory input for all requests. - `radius` number — Specify a radius, in meters, which will be used to filter out ineligible vehicles for each order. The pickup location of an order will act as the center of the circle when identifying eligible vehicles. Valid values for radius are \[1, 10000\]. - `pickup_eta` integer — Specify a duration, in seconds, which will be used to filter out ineligible vehicles for each order. Any vehicle which would take more time than specified here, to reach the pickup location of a given order, will be ruled out for assignment for that particular order. Valid values for pickup_eta are \[1, 3600\]. - `driving_distance` number — Defines a driving_distance filter, in meters. If a vehicle needs to drive further than this distance to reach a pickup location, it will not be assigned to that order. Valid range of values for this filter is \[1, 10000\]. - `options` object — Configure the assignment constraints and response settings. - `travel_cost` 'driving_eta' | 'driving_distance' | 'straight_line_distance' — Choose a travel cost that will be used by the service for assigning vehicles efficiently from a set of qualifying ones. - `dropoff_details` boolean — When **true**, the service returns the drop-off steps for each trip and related details in the response. Defaults to **false**. - `order_attribute_priority_mappings` object[] — Collection of rules for assigning custom priority to orders based on their attributes. In case an order satisfies more than one rule, the highest priority score from all the rules satisfied, would be the effective priority score for such an order. - `attribute` string, required — Specify the name of the attribute. The attribute is compared to the keys (of each key:value pair) in orders.attributes during evaluation. - `value` string, required — Specify the desired value of the attribute to be applied for this order. value provided here is compared to the values (of each key:value pair) in orders.attributes during evaluation. - `operator` string, required — Specify the operator to denote the relation between attribute and the value specified above. The attribute , operator and value together constitute the condition that an order must meet to assume the specified priority. We support the following operators currently: * Equal to (==) * Less than (<) * Less tha equal to (<=) * Greater than (>) * Greater than equal to (>=) * Contains (contains) Please note that when using "contains" operator only one value can be specified and the corresponding attribute must contain multiple values when defined for an order. - `priority` string, required — Specify the priority score that should be assigned when an order qualifies the criteria specified above. A higher value indicates a higher priority. Valid values are \[1,10\]. - `vehicle_attribute_priority_mappings` object[] — Collection of rules for assigning custom priority to vehicles based on their attributes. In case a vehicle satisfies more than one rule, the highest priority score from all the rules satisfied, would be the effective priority score for such a vehicle. - `attribute` string, required — Specify the name of the attribute. The attribute is compared to the keys (of each key:value pair) in vehicles.attributes during evaluation. - `value` string, required — Specify the desired value of the attribute to be applied for this vehicle. value provided here is compared to the values (of each key:value pair) in vehicles.attributes during evaluation. - `operator` string, required — Specify the operator to denote the relation between attribute and the value specified above. The attribute , operator and value together constitute the condition that a vehicle must meet to assume the specified priority. We support the following operators currently: * Equal to (==) * Less than (<) * Less tha equal to (<=) * Greater than (>) * Greater than equal to (>=) * Contains (contains) Please note that when using "contains" operator only one value can be specified and the corresponding attribute must contain multiple values when defined for a vehicle. - `priority` string, required — Specify the priority score that should be assigned when a vehicle qualifies the criteria specified above. A higher value indicates a higher priority. Valid values are \[1,10\]. ## Response `200` - object - `status` integer — An integer indicating the HTTP response code. See the [API Error Handling](https://docs.nextbillion.ai/optimization/driver-assignment-api#api-error-handling) section below for more information. - `message` string — Displays indicative error message in case of a failed request or operation. Please note that this parameter is not returned in the response in case of a successful request. - `result` object — An object containing the details of the assignments. - `trips` object[] — An collection of objects returning the trip details for each vehicle which was assigned to an order. Each object corresponds to one vehicle. - `trip_id` string — Returns a unique trip ID. - `vehicle` object — Returns the details of the vehicle, assigned order and the trip steps. - `id` string — Returns the ID of the vehicle. - `steps` object — A collection of objects returning the sequence of steps that the vehicle needs to perform for a trip. - `type` 'pickup' | 'dropoff' | 'ongoing' — Returns the type of the step. Currently, it can take following values: * **pickup:** Indicates the pickup step for an order * **dropoff:** Indicates the dropoff step for an order. It is returned only if dropoff_details was **true** in the input request. * **ongoing:** Indicates a step that the vehicle needs to complete on its current trip. This is returned in the response only when remaining_waypoints input was provided for the given vehicle. * **intermediate\_waypoint:** Indicates an intermediate stop that the vehicle needs to complete in case multiple dropoffs are provided in the input. - `order_id` string — Returns the ID of the order. In case the step type is **ongoing**, an empty string is returned. - `location` Location — Location info. - `lat` number, required — Latitude of location. - `lon` number, required — Longitude of location. - `distance` integer — Returns the driving distance, in meters, to the step's location from previous step's location. For the first step of a trip, distance indicates the driving distance from vehicle_current_location to the step's location. - `eta` integer — Returns the driving duration, in seconds, to the step's location from previous step's location. For the first step of a trip, eta indicates the driving duration from vehicle_current_location to the step's location. - `vehicle_current_location` Location — Location info. - `lat` number, required — Latitude of location. - `lon` number, required — Longitude of location. - `unassigned_orders` object[] — A collection of objects listing the details of orders which remained unassigned. Each object represents a single order. A null value is returned if there are no unassigned orders. - `order_id` string — Returns the ID of the order which remained unassigned. - `unassigned_reason` string — Returns the most probable reason due to which the order remained unassigned. - `available_vehicles` string[] — A collection of vehicles IDs that were not assigned to any orders. A null value is returned if there are no vehicles without an order assignment. - `alternate_assignments` object[] — An array of objects containing the details of the potential, alternate vehicle assignments for the orders in the input. This attribute will not be returned in the response if the alternate_assignments was not provided in the input. Each object represents alternate assignments for a single order. - `order_id` string — Returns the order ID associated with the alternate assignments. - `assignments` object[] — An array of objects containing the details of the alternate vehicle assignments. Each object represents an alternate vehicle assignment. - `vehicle_id` string — Returns the vehicle ID which could potentially be assigned to the given order. - `pickup_eta` integer — Returns the ETA to the order's pickup location for the given vehicle. --- [API](https://skmtc.net/nextbillion-ai/apis/one-spec-service.md) · [All operations](https://skmtc.net/nextbillion-ai/apis/one-spec-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nextbillion-ai/one-spec-service/versions/b647f1808dda/schema)