Route Optimization Fast API

Introduction

Nextbillion.ai’s Route Optimization Fast API solves for the optimization of a Multi(or single) vehicle routing problem. There are two components to API

1. Optimization POST - Use this method to submit the input for your VRP.

2. Optimization GET - Retrieve the status of a submitted VRP using a unique reference ID.

General Notes:

• A "task" is either a job, a pickup or a delivery

• The expected order for all location arrays is [latitude, longitude]

• All the timestamps are UNIX in seconds and other time-related parameters’ units are in seconds.

• All the distance-related parameter units are in meters.

• A time_window object is a pair of UNIX epoch timestamps in the form [start, end].

• Cost values in output are the ones used in the optimization objective.

Optimization POST

Use this method to configure the constraints and properties of the optimization problem that you need to solve. Use the fundamental objects - vehicles, jobs, locations and shipments to emulate the scenario that your business needs to optimize. You can choose to use either one of jobs and shipments or use both of them.

The objective to be achieved during optimization can be defined in the optionspart. Once an Optimization POST request is successfully submitted, the API will return a unique task ID in the acknowledgement response. Use this unique ID to retrieve the actual solution using the Optimization GET Method.

Request Parameters

Request Body

Response Schema

Optimization GET Request

Use this method to retrieve the optimized solution for the optimization tasks created using the Optimization POST Method.

Request Parameters

Response Schema

Object Overview

Location Object

• The location object contains a list of coordinates in [lat, lon] format. Other properties in the request will refer to coordinates specified in the location object via their index parameter. An example of a location object can be understood via the following table

• "Location" : "51.388997,-0.119022 | 51.391915,-0.103666 | 51.369777,-0.10438 | 51.365014,-0.105654 | 51.351818,-0.014773"

  Index	Location
  0	51.388997,-0.119022
  1	51.391915,-0.103666
  2	51.369777,-0.10438
  3	51.365014,-0.105654
  4	51.351818,-0.014773

• So for example, if in the "vehicles" property, the start_index parameter is set to 2, then the starting coordinate for that vehicle is 51.369777,-0.10438 as per the above table.

Vehicles Object

vehicles object describes the characteristics and constraints of a vehicle that will be used in a multi-vehicle routing problem. Some points to consider about vehicles object:

• The users can set a start or an end location of their choice as long as it is present in the locations object. The vehicle’s start and end locations can be different from job locations.

• If the optional start_index parameter is not used, the route will start from the location of the depot to which the vehicle is assigned. Otherwise, the route will start at the first visited task whose choice is determined by the optimization process.

• If optional end_index parameter is not used, the route will end at the location of the depot to which the vehicle is assigned. Otherwise, the route will end at the last visited task whose choice is determined by the optimization process.

• In order to request a round trip, you can specify both start_index and end_index with the same location index. Alternatively, the users can assign a depot to the vehicle and leave start_index and end_index unspecified to make the vehicle start and finish at the depot’s location.

• breaks parameter can be used to plan the breaks that the driver needs to take.

• costs of the vehicles can be used to prefer lower cost vehicles over higher cost vehicles.

Capacity Restrictions

• Use amounts (capacity for vehicles, delivery, and pickup for jobs, amount for shipments) to describe a problem with capacity restrictions. Those arrays can be used to model custom restrictions for several metrics at once, e.g. number of items, weight, volume, etc. The order and number of the dimensions must match the order & number of dimensions in the capacity parameter of the vehicle object. For example

  • If capacity = [quantity, weight, volume], each of the parameters (delivery, pickup, amount) must contain [quantity, weight, volume] information.

• A vehicle is only allowed to serve a set of tasks if the resulting load at each route step is lower than the matching value in capacity for each metric. When using multiple components for amounts, it is recommended to put the most important/limiting metrics first.

• It is assumed that all delivery-related amounts for jobs are loaded at vehicle start, while all pickup-related amounts for jobs are brought back at vehicle end.

• All capacity values are integers. It is recommended that the user should convert any non-integer values rounded up to the nearest integer. For example, if a shipment has a weight of 14.57 kg, it is recommended to use 15 in the capacity property.

Skills Restrictions

Use skills to describe a problem where not all tasks can be served by all vehicles. Job skills are mandatory, i.e. a job can only be served by a vehicle that has all its required skills. In other words: job j is eligible to vehicle v if and only if j.skills is contained in v.skills. This definition implies in particular that:

• a task without skills can be served by any vehicle;

• a vehicle without skills can only serve tasks with no particular skills

In order to ease modeling problems with no skills required, not providing a skills key defaults to providing an empty array.

Task Setup & Service times

Setup times serve as a means to describe the time it takes to get started for tasks at a given location. This model has a duration that should not be re-applied for other tasks following at the same place.

Service times on the other hand are the times needed for performing services. If for example, a location has 3 different tasks to be completed, each task might have a different service duration.

So the total "action time" for a task is setup + service upon arriving at a new location or service only if performing a new task at the previous vehicle location.

Depots

Depots are congregation points for vehicles. A Depot can contain multiple vehicles. It has the following key features.

• A depot is assumed to have infinite inventory.

• If the depot attribute is set for a vehicle, the start_index of a vehicle will need to be set to the location index set by the depot attribute. As an alternative, you can simply not set the start_index and internally, it will be set to the depot’s location. However, the end location for a vehicle can be different from the depot’s location.

• If the depot attribute is set for a vehicle, and end_index is not set, the end location for the vehicle will be set to the depot’s location_index.

• There is no restriction on the number of vehicles a depot can contain but one vehicle can only be assigned to one depot.

API Query Limits

• Nextbillion.ai allows a maximum rate limit of 300 queries per minute or 5 queries/second for continuous requests.

  Note: We can increase the quota if needed on request. Contact [email protected] for more details.

• At any point the maximum number of pending requests that the queue can hold is 25, for a given API key. New requests for the same key can be submitted once some of the pending requests are resolved.

• A maximum of 4000 locations can be added to the locations object

• A maximum of 4000 tasks can be added in an optimization problem. Number of tasks is calculated as number of jobs + 2 * (number of shipments).

• Maximum value that can be provided for truck_weight is 100,000 kg.

• Maximum dimensions for truck_size are 5000 cm for length, 5000 cm for width, 1000 cm for height.

• When using traffic_timestamp or truck related parameters in the routing property of options attribute, please expect a higher request processing time, especially if the number of locations provided in the request is also high.

API Error Codes