The Multi-Vehicle Route Optimization API automates the process of taking a list of orders and stop locations and building the most efficient routes to serve them. It optimizes routes while taking into account the challenges fleets face every day—from managing order flows and resources (drivers and trucks) to meeting strict customer time windows and service-level agreements.

This RESTful API is built on the same routing algorithm as our Appian DirectRoute and DRTrack user interfaces. It can be integrated into any solution that requires a powerful, trusted routing engine with a 20-year track record of serving large fleets with complex routing problems.

Building Realistic Routes

The API allows you to pass a wide range of parameters as inputs so the routing solution returned can realistically be executed on road. These parameters account for a fleet’s many constraints when routing and scheduling, including:

For Stops/Orders

• Time Windows
• Location
• Stop Time
• Order Volumes

For Drivers

• Driver Skills
• Breaks
• Maximum Drive Time
• Maximum Drive Time before Layover
• Min and Max Layover Time
• Target Work Time
• Normal Work Day
• Re-dispatching rules
• Max Work Time

For Vehicles

• Special Equipment Needs
• Max Distance
• Capacity (Tied to Volume Provided on Order Level)

For Routes

• Early/Late Start Time
• Normal Start Time
• Latest Finish
• Route Start/End Date

What is a Route Solution?

Based on your inputs, a route Solution is returned that contains all of the orders/stops (routed and unloaded), the routes with stop sequences assigned, and the solution statistics (miles, hours, arrive/departs, cost, violations, etc.) The illustrations below show how the routing algorithm turns orders into routes.

Note: In this example, all of the stops passed into the algorithm were assigned a route and sequence which was optimal, given the constraints used. Depending on those constraints, however, the API may not assign all orders to a route. They will remain unloaded and will be returned by the API as such.

API Basic Use Cases

This API can not only be used to build efficient routes, but also adjust those routes as needs change throughout the day. API endpoints include:

• Solve - Send in orders/stops, resources (driver/trucks), and rules/settings and generate a solution including the number of routes, which stops are on which routes, the sequence of those stops, and solution statistics.
• OptimizeSequence - Send in routes with a stop sequence to try to generate a more optimized sequence of stops while adhering to all of the rules/settings that are passed.
• OptimizeFull - Also known as “optimize between,” you can send in multiple routes and the algorithm will return whether moving stops between routes will create a more optimal solution while adhering to all rules and settings passed in.
• Suggest - Send in a route or group of routes and an unrouted order/stop. The algorithm will return a route/sequence suggestion for the stop as well as the statistics associated with adding the stop to the routes suggested.
• RecalculateOperation - Re-calculate will take in existing routes and settings, re-initialize the routes, and return back the routes as calculated by the algorithm. This can be used to tweak configurations or settings, and then update the route plans to match.
• InvertOperation - Performs an invert operation on the supplied routes. This reorders the stops last to first for each leg.
• MoveStopsOperation - This endpoint allows orders to move from one route to another. This is commonly used with Suggest or Recalculate.
• UnloadStopsOperation - This operation allows you to remove (unload) a stop from a routed solution. This is commonly used with Suggest or Recalculate.
• UnloadRoutesOperation - This operation is used to unload all stops from a given route and return them to unloaded status. Can also be used to unload all stops from all routes.

The API requires a licensing agreement with Trimble MAPS. Contact us to learn more or to request a demo.

Authorization to consume the multi vehicle route optimization API follows a JSON Web Token (JWT) based authentication pattern. In order to consume this API, a client will need to be provided with a Company, Username and Password combination, then retrieve an access_token to use with these services. The access_token will need to be included in the form of a bearer HTTP header in the form of Authorization: bearer <access_token>.

For more details on the authentication process, please see the Identity Documentation.

In order to use the Multi-Vehicle Route Optimization API, you will need to understand the following concepts used throughout the API documentation.

Solving Routing Problems

Building out routes for an entire fleet is, in short, a “Problem.” That’s why Solve is the main endpoint for the Route Optimization API. It takes in all of the information about the orders a fleet has to service and returns a Solution. The Solution includes the route plan as well as statistics about the plan—things such time, distance and cost.

The other API endpoints are ways to modify, update or attempt to improve (optimize) that Solution.

Constraints

The term constraints is used generally for things the routing algorithm has to “keep in mind” to be sure it's solving the routing problem in a useful way. Constraints include customer constraints, such as time windows and order volumes, and fleet constraints, such as available equipment and drivers—based on max work time and required breaks.

There is also a constraints object that allows you to control how the routing algorithm itself behaves. It includes settings such as how far apart stop locations can be on the same route, how many total stops can be on a route, and the maximum wait time at a stop.

Violations

A violation is a term used generally for anything that fails to comply with constraints. The routing algorithm always tries to avoid violations but, in some cases, it may return the violation and leave it to the user to decide whether it’s an acceptable violation in order to complete a route. (For example, maybe it’s OK for a driver to return to the depot late that particular day?)

What is a Stop?

A stop represents when a truck is stopping for a delivery or a pickup. Each stop is defined in API requests by the following information:

• orders: An Order represents a sales order, transfer order, or return material authorization (RMA) in an enterprise resource planning (ERP) application. At a stop, there may be a single order or multiple orders. On a given order, there could be one or more line items. Line items provide additional information about the order, such as how long it takes to unload it and the order volume (pallets, pieces, etc.)

• config: The Config contains information or constraints related to the stop that are necessary to ensure routes the API generates will work in the real world. That includes details such as available dates and time windows for a delivery or pickup.

• coordinates: A longitude, latitude pair representing the exact location of the stop.

Unloaded Stops

Unloaded stops are any stops that are unassigned to a route and need to either be distributed to existing routes or loaded onto new routes. A loaded stop is a stop that has been assigned to a route. Unloaded stops are both:

• An input into the API when passing the POST request payload.
• An output in the API response (Solution), identifying stops that didn’t “fit” into any routes because of time, resources or other constraints.

How to Shape Routes

When generating a route via the Solve endpoint, you can pass not only the unloaded stops, but also a wide range of additional details to ensure the API generates the best routes possible for a particular fleet. In addition to unloaded stops, requests to Solve can contain:

• routes: Routes are already built and defined routes the algorithm can be tasked with building upon or further optimizing. Routes information helps the algorithm determine whether it can assign orders to existing routes as well as how it can avoid any conflicts with existing routes—in particular with resource (driver/asset) allocation. The prime example is when a company has fixed or static routes and the algorithm needs to be used for slotting of new or off-day deliveries or even just used as a route calculator.
• availableRoutes: These settings let the routing algorithm know about the resources that are available to be used when it generates routes. It includes a list of drivers, vehicles and other rules or constraints on the routes themselves. The difference between routes and availableRoutes is availableRoutes is passed in with the intention of being “empty” and the algorithm solving the problem using the values and constraints passed in. Routes, however, indicate at least some of the Solution has previously been calculated.
• config: Config settings are available for each stop, as noted in the Stop definition. These are additional, Solution-level settings that allow you to customize the way the routing algorithm behaves. Config settings include everything from high-level settings, such as distance units (miles or kilometers) to behaviors by which orders are able to be consolidated.

The Route Optimization API has several endpoints designed to be used individually or in tandem, allowing you to complete different routing and optimization workflows. Those workflows include:

• Dynamic Fleet Routing
• Route Calculation
• Fixed Route Optimization
• New Order Placement
• Inverting a Route
• Unloading From Routes
• Moving a Stop from One Route to Another
• Recalculating a Solution
• Authentication

Dynamic Fleet Routing

This is the most common use case, where you want the algorithm to generate the best possible answer in terms of number of routes needed for a group of orders. To do this, you would:

• Use the Solve endpoint to generate the Solution. The API response includes the orders, with route and stop sequence, and the route and solution statistics.

• The system can perform a between-route optimization (attempting to move stops between routes to reduce the overall cost of the solution) automatically or it can be triggered after the fact by sending the return from the Solve endpoint into the OptimizeFull endpoint.

Route Calculation

Another common use case involves orders that already have a route and sequence assigned to them and are stored in an ERP. These represent fixed or static routes. Based on things such as the frequency of customer ordering, order volume and ad-hoc or off-day deliveries, the “daily” route may vary wildly from the fixed route assignment stored in an ERP.

Using the Solve endpoint with orders that have a route and sequence will return route and solution statistics as well as route violations (time windows, capacity, etc.) that need to be considered.

Fixed Route Optimization

Based on the results from the Route Calculation workflow, you might want to either have the algorithm optimize the sequence of routes or move stops between routes to create a lower cost solution for that particular day. You could call the Solve endpoint first to receive route and solution statistics for an end user to view in an UI, and then call OptimizeSequence to receive updated statistics for the user to view.

Alternatively, the Solve endpoint isn’t needed. You could call the OptimizeSequence or OptimizeFull endpoints to just receive updated route statistics.

New Order Placement

Once a solution has been created or simulated, it is ready for execution. This doesn’t usually mean that planning is over; there are several instances where orders need to be added to a solution either before the trucks have left the terminal/warehouse/distribution point or while that route is on the road.

You have several options to solve this use case:

1. Pass an entire solution back into the Solve endpoint with route and sequence assigned to orders that have previously been routed. New orders that need to be routed around the existing solution would be passed in without a route and sequence. The algorithm will add the new orders to the appropriate slots on the existing routed solution. This is best used prior to the routes being on the road.

2. Another approach would be to use the Suggest endpoint. This endpoint gives suggestions for new order placement in a previously routed solution. The response of this endpoint is suggestions of routes (that have already been created) where the new order could be inserted with incremental distance, cost and any violations adding that stop to the route would cause. You could build a UI experience on top of this endpoint to display the best suggestions and allow the end user to load a single stop onto a route via the Solve endpoint. Suggest could be used to slot orders onto routes on the road already. The user controls what route details are sent in—only sending in stops that have yet to be completed and the new order would let the algorithm put the stop in the appropriate sequence based on the stops remaining.

Inverting a Route

Based on planner or driver preference, an entire route may need to be inverted (have the sequence reversed). An example would be if the last stop on a route ends away from the DC, but the driver wants to end closer to the distribution point. In this case, the entire sequence of a route could be reversed.

Using the InvertOperation endpoint will return the route passed in with the sequence reversed, as well as the route and solution statistics. This can be used on multiple routes or a single route.

Unloading From Routes

There are times when orders need to be removed from a route, either before or after it’s in progress. There are also times when an entire route needs to be unloaded. In these cases, use the UnloadStopsOperation and UnloadRoutesOperation endpoints. You pass in routes and stops you wish to unload and are returned any unloaded stops as well as the updated route plan/statistics for the remaining solution.

Moving a Stop from One Route to Another

An integral part of route editing is the ability to move stops from one route to another, usually through a UI. That UI could call the MoveStopsOperation endpoint to move an order from one route in the solution to another. The system would then return the updated route and solution statistics as well as any violations on the destination route caused by moving that order.

This is commonly used with the Suggest endpoint, which can be used on routed stops to find another candidate route to which a stop can be moved. Once the user identifies this candidate route, the MoveStopsOperation can make the change for the user.

Recalculating a Solution

There will be some instances where adding a constraint or changing a setting will change a particular route or the solution. (For example, adding a driver to a route or changing an optimization penalty.) To get the updated route or solution statistics, the Solve endpoint is appropriate, BUT it is an asynchronous call.

To get the same recalculation, the RecalculateOperation endpoint would be faster due to its synchronous nature. This doesn’t solve for unloaded stops, but if a user just wants to update a data element and not use the algorithm for anything other than a route calculator, RecalculateOperation is a better choice.