Vehicle Routing and Scheduling API provides capabilities to create optimized routes for a fleet of vehicles, taking into account various business rules, such as vehicle capacity or time windows, as well as external factors such as road traffic.
The API supports a wide range of real-world business rules and constraints that can be mapped to same-day or next-day delivery or distribution operations at last and middle mile.
The API object model is built with optional blocks, which allows modelling of transport operations for various business verticals and use cases, not limited to goods delivery or distribution.
This documentation is generated automatically from service OpenAPI 3.0 JSON schema.
In case you are already familiar with the main concepts of route optimization and Vehicle Routing Problem, the Common definitions secion of this documentation covers main concepts and terms used in the API.
Please see our public GitHub repository for example client and VRP tasks in JSON format: https://github.com/routinghub/vrs-examples
For complete reference of API request and response formats, please see interactive documentation for API methods.
The OpenAPI 3.0 JSON Schema for the service is fully compatible with OpenAPI Generator which can be used to generate API client in your development language from service OpenAPI schema.
Routing Solution is a set of optimized vehicle routes, created from a user-defined Routing Problem.
A vehicle route is a sequence of site visits, that is created by optimization engine such that all constraints and rules are fulfilled, and total cost of transportation is minimized.
When building a routing solution, the optimization engine minimizes the total cost of transport operations, which is defined as a weighted sum of total transit cost for all routes, and constraints violations costs.
There are two types of vehicle and soft constraints violations costs that are used in the API:
A fixed cost is added to the total cost once on soft constraint violation or when new vehicle is added to Routing Solution;
A weighted cost expresses how much a constraint was violated - for instance, how late a vehicle has arrived at a site after the time window end, or how much the driver exceeded maximum working hours. In terms of vehicle costs, weighted cost is transit distance and total time, each multiplied by a cost coefficient to allow balancing between distance and time minimization.
During optimization, the engine minimizes vehicle costs together with constraint violation costs. The optimization process does not differentiate which constraint has been violated, or which vehicle cost component contributes to the total cost, and instead compares only the absolute cost values of individual routes, or total sum of all costs of all routes and constraints.
This approach allows optimization of complex, multi-objective optimization problems with mixed soft and hard constraints and complex relationships.
In specialized decision-making software, such an approach is commonly referred to as the Weighted Sum Model (WSM).
The routing problem submitted for optimization may define certain business rules, or constraints, which can take one of the following types:
Depending on the particular use case, both soft and hard constraints can be useful to model required scenarios.
For example, a time window is normally defined as a strict constraint, such that late or early arrivals to a site are not allowed.
However in situations when the load to be delivered is significantly over the available fleet capacity, small lateness (time window violation) can be tolerated to handle additional load.
In this case, a time window can be used as a soft constraint, with a carefully balanced value of violation cost to permit only a certain percentage of violations. The violation cost for soft time windows is each minute of late or early arrival at a site, multiplied by user-defined constant, that will be compared with other cost components and minimized as a part of total cost.
Unserved sites are sites which were not allocated to any vehicle in the routing solution.
There are several reasons why a site may become unserved, which are reported back to user in the API response for further analysis:
Each site in the routing problem for optimization has a cost of non-performing the visit to this site. When not defined, a big default number is used for unserved cost.
Unserved cost is a limit of all cost values, associated with site visit. For instance,
a site with unserved cost of 1000 will never be served by a vehicle that has
distance cost per kilometer equals to 1, and distance between any other site to the site
in this example exceeds 1000km.
Another scenario when it may be useful to alter the default unserved cost value is when the capacity of the fleet is less than the volume of sites to be served.
In such scenario, unserved cost can be used as a priority value to indicate which sites should be served in first place.
Planning Horizon is a range of time of the whole Routing Problem, from the earliest to latest depot or vehicle shift time window.
For example, a Routing Problem can be submitted for optimization a day in advance
before execution and contains orders and driver’s shifts for the next day,
starting from 08:00 and ending at 21:00. In this case, the planning horizon is 13 hours.
The optimization engine does not limit the planning horizon, however extremely long route planning intervals (multi-day or multi-week) may require additional tuning by our development team for optimal performance.
Site is a location to be visited by a vehicle, associated with a job to be performed during the visit.
The location of a site is defined with geographic coordinates. In case your dataset contains street addresses, the geocoding is required, e.g. each address should be referenced to a geographical location.
We recommend Google Maps Geocoding API or a similar third-party API for geocoding purposes.
Sites with the same geographical location, intersected time windows and other compatible properties are referred to as colocated sites.
A site can have multiple additional constraints, such as time window, required vehicle capabilities, job type (pickup or delivery), duration of the job, duration of parking or other operations before the job, duration of goods loading at the depot and so on.
See Site type reference for a complete list
of supported constraints.
Time window is a range of time that limits certain operations, for example depot opening hours, driver’s shift time, or a range of time when an order can be picked up or delivered to the customer.
A job is an operation that a vehicle (or it’s driver) performs on site. In case of goods transportation, the job represents pickup or delivery operation. The API supports mixed pickup-and-delivery operations, covering three possible scenarios:
A job has duration, which is the time required to complete the job after arrival.
For colocated sites, it is also possible to define a preparing duration - time for common operations, performed before multiple jobs at the same location, for example vehicle parking.
Depot is a special type of site, where vehicles start and optionally finish routes. A routing problem can have multiple depots, which can be starting or ending sites for particular vehicles.
A depot shares many of its properties with sites, and supports additional constraints such as depot throughput (the amount of load a depot can release per hour).
See Depot type reference for a complete list
of supported constraints.
Vehicle is a physical vehicle that starts from a depot, visits sites in optimal order, and returns to a depot at the end of the route. Start and finish depots are optional.
A vehicle has capacity, defined in volumetric or abstract countable units to limit the amount of transportable load. Additionally, a vehicle can have one or more capabilities that define functional properties or type of the vehicle (for example, the ability to carry only certain types of load, availability of a forklift or refrigeration system and so on).
A vehicle can start and finish its route at any time within the depot time window, performing one or more roundtrips to the depot to pick up or deliver picked up load. Optionally, a vehicle can have one or more associated driver’s shifts.
See Vehicle type reference for a complete list
of supported constraints.
A shift or a driver’s shift is a range of time when a vehicle can drive, visiting sites and performing jobs.
By default, each vehicle has one driver’s shift, with the time window equal to the vehicle’s depot time window. Depending on the use case, it is possible to define multiple driver’s shifts to map availability of drivers to available vehicles. When a driver's shift is defined, the vehicle will operate within the limits of the defined driver’s shift, returning to the depot to start a new shift.
The API does not provide capabilities to define drivers, however it is possible to limit total shift duration to model driver’s working hours limit. It is also possible to limit total driven distance or energy spent by a vehicle, for refueling or EV recharging constraints.
The API allows definition of load size to be picked up or delivered for each site, depending on the site job type.
The load can be defined in volumetric dimensions, using weight in kilograms, or volume in cubic meters. The weight and volume can be specified explicitly and are completely independent. In the case when weight is specified and volume is not specified, the latter is calculated using a common volumetric factor, and vice versa.
In addition to weight and volume, the load can be specified in non-metric countable units (boxes, kegs, pallets, etc.). Countable units are completely independent of weight and volume and can be combined with volumetric units if required.
The API for vehicle capacity definition is the same as for site load definition, and uses three independent capacity dimensions (weight, volume and countable units).
The API supports definition of load categories, and a simple rule system to allow or restrict mixing of certain load categories during a single vehicle roundtrip.
Depending on a use case, this functionality can be used for transportation of load with different safety classes, or, for example, for transportation of non-mixable types of passengers.
Incremental optimization allows adding new sites/vehicles/constraints to already optimized routing task, and perform re-optimization taking into account loading and site visit status of the optimized routes.
The Incremental Optimization API can be used to mix pre-planned and dynamic orders, when dynamic orders are arriving in real-time and further optimized in batches.
The optimization engine uses a pre-calculated matrix of site-to-site routes to estimate transit time and distance between any two sites of the routing problem.
There are three types of routing (matrix) data sources which
can be defined in the Routing Problem options:
Other matrix types supported by API such as straight line distance are intended for requests debugging.
The optimization engine is capable of using road traffic information in the form of time-variable transit matrices.
When using HERE Maps traffic, it is possible to specify time points, corresponding to the time of the day when traffic in the geographical area of the routing problem changes compared to free flow road speeds. For example, for city areas usually there are morning and evening traffic peaks around certain hours of the day.
In case when the user-supplied transit matrices are used, it is also possible to specify a time point for each matrix, that indicates time of the day when a particular matrix should be used.
The API supports wide range of operational scenarios, covering same-day or next-day route planning. In addition to stable API functionality, it is also possible to introduce customer-specific constraints, that remain hidden from the public API and are usable only with a particular API key.
We are aiming to provide unified API object model, and iteratively move new functionality from customer-specific use cases to common public API.
At the moment, we do not provide ways to extend API functionality with customer's own code. The internals of our route optimization engine contain highly optimized algorithms, which we carefully extend to cover new operational use cases and constraints on customer's request.
A Vehicle Routing Problem requires significant time to obtain a good solution.
Internally, optimization engine uses multiple servers and multiple CPU cores on each server to speed up the search and try millions of route combinations per second. The end-to-end search time varies with the number of sites and vehicles, and is usually in the range between 30 seconds to 10 minutes. The number of parallel optimization requests is limited by your API key quota.
There are several modes that control the quality of Routing Solution,
as well as optimization time: debug, normal and high.
In 99% of the use cases, a normal mode must be used. For development purposes, we recommend to use debug
mode for quick evaluation of cost and constraints model.
The Vehicle Routing and Scheduling API has asynchronous REST interface. Since route optimization requires significant time to process a request, the communication with the API is made via two REST endpoints:
/add endpoint to submit JSON definition of Routing Problem,
and receive unique id for further polling of result;/result endpoint to poll for optimization status and
result when optimization completed.Queues new route optimization request for processing. Returns created optimization task ID.
| fleet required | |
| sites required | |
| depots | |
| options | |
| constraints |
Task has been queued for execution.
| Location |
| id required | |
| status required | enum: created | started | completed | cancelled Current status of an asynchronous task. Status values:
The status of a task will change only in the following ways during execution:
|
| status_log required |
Invalid or empty JSON in POST request body
Request is not authorized
Server error during request processing
Queues new incremental route optimization request for processing. Returns created optimization task ID.
| previous required | |
| new required | New entities for an incremental route optimization request:
Specified entities will be optimized together with previously optimized and partially executed vehicle routes. |
Task has been queued for execution.
| Location |
| id required | |
| status required | enum: created | started | completed | cancelled Current status of an asynchronous task. Status values:
The status of a task will change only in the following ways during execution:
|
| status_log required |
Invalid or empty JSON in POST request body
Request is not authorized
Server error during request processing
Returns result of optimization task if task is completed, or execution status.
Task execution completed
| result required | |
| id required | |
| status required | enum: created | started | completed | cancelled Current status of an asynchronous task. Status values:
The status of a task will change only in the following ways during execution:
|
| status_log required |
Task is executing
Request is not authorized
Requested task is not found.
Server error during request processing
OK