Optimization API v2 | API Docs (original) (raw)

The Optimization v2 API is an API for calculating efficient plans for vehicles to visit multiple locations. These are commonly known as vehicle routing problems.

The Optimization v2 API enables you to submit vehicle routing problems in the form of routing problem documents describing the number of vehicles in your fleet, locations to be visited, and other constraints that are relevant to your real-world problem. The API returns an optimized solution for your routing problem as a solution document that describes a route plan for each vehicle.

Quick summary​

  1. POST to /optimized-trips/v2?access_token=YOUR_MAPBOX_TOKEN to submit a routing problem, and save the id from the JSON response.
  2. GET from /optimized-trips/v2/{id}?access_token=YOUR_MAPBOX_TOKEN to check the status and receive the result when it is complete.
  3. GET from /optimized-trips/v2?access_token=YOUR_MAPBOX_TOKEN to list all your account's submitted routing problems and their processing statuses.

Submit a routing problem​

post

https://api.mapbox.com

/optimized-trips/v2

To submit a routing problem, make a HTTP POST request with a Content-Type of application/json, and submit the routing problem document JSON as the POST body.

Example HTTP request​

Example cURL request​

202 Accepted​

The 202 response to a request is a JSON object that contains the following properties:

Property Type Description
id string This is a unique ID for the submitted request. Save this value. It is needed to retrieve the status and results of your submission.
status string This indicates whether the routing problem submission is pending, processing, or complete ("ok"). complete ("ok") indicates a successfully submitted routing problem, not a solved problem.
status_date string The date when the status was updated.

The 202 response body has a Content-Type of application/json, and looks similar to this:

The id value in this response is a unique ID for the request you submitted. Save this value, then use it to retrieve the status and results of your submission.

Retrieve a solution​

get

https://api.mapbox.com

/optimized-trips/v2/{id}

To retrieve a solution, you must have the id generated when the routing problem was submitted. If you did not save the id for your submission, you can retrieve a list of all your submissions to find the id.

Refer to the solution document section to better understand the solutions that you receive from the Optimization v2 API.

Example HTTP request​

Example cURL request​

202 Accepted​

No solution is available for your routing problem yet. The request is either waiting to be processed or is processing.

200 OK​

This response means that the solution has been posted. The body of the HTTP response is the solution JSON document.

List submissions and their status​

get

https://api.mapbox.com

/optimized-trips/v2

You can fetch a list of all the routing problems you have submitted along with their current processing statuses. To do so, make a HTTP GET request against the base URL.

Example HTTP request​

Example cURL request​

200 OK​

You will receive a JSON response body that is structured as follows:

The values for id are the unique IDs generated each time a routing problem is submitted successfully. Use the id to retrieve a solution for one of your submitted routing problems.

Routing problem document​

Routing problems are JSON documents with a defined schema.

Conventions​

Overview​

The root object in the routing problem document contains five elements:

Each of these root elements is described in a separate section below.

Version​

Required. This object describes the schema version of the routing problem document. Only the value 1 (as a number) is supported.

Locations​

Required. A location is a physical point in space that needs to be visited by the vehicles in your routing problem. You must refer to a location from services or shipments for a location to be visited.

Field Description
name Required. The unique name of a location. This name is used by other objects when they refer to a place.
coordinates Required. An array of two numbers representing a location in "longitude,latitude" order.

Example request object - locations​

Vehicles​

Required. A vehicle is a car, truck, or similar machine that travels between your defined locations. You need to add at least one vehicle to generate a solution.

Field Description
name Required. The unique name of a vehicle. The name is displayed in the solution document.
routing_profile Optional. Defines which profile to use to calculate travel times/distances for this vehicle. The default value is mapbox/driving. Valid values include: mapbox/driving, mapbox/driving-traffic, mapbox/cycling, mapbox/walking.These correspond to the profiles available on a Mapbox Directions routing profile.
start_location Optional. The location where the vehicle should start its route. If not supplied, the vehicle starts at a location that minimizes the route according to the objectives that you set.
end_location Optional. The location where the vehicle should end its route. If not supplied, the vehicle finishes at a location that minimizes the route according to the objectives that you set.
capacities Optional. How many units of an item can be carried by a vehicle. You can define as many capacities as needed. When you define shipments, you can describe how many units of each capacity these shipments require. The optimizer ensures that a vehicle's capacity is never exceeded.
capabilities Optional. The capabilities of a vehicle. When defining shipments, you can require that only vehicles with certain capabilities should serve those locations.
earliest_start Optional. The earliest time this vehicle can start operating.
latest_end Optional. The latest time this vehicle can finish operating.
breaks Optional. Define when mandated breaks for vehicles can begin and end, and how long a break can last. An array of required objects with earliest_start (timestamp string), latest_end (timestamp string), and duration (integer seconds) properties.
loading_policy Optional. How packages must be loaded/unloaded from the vehicle. For example, packages loaded onto the vehicle first cannot be unloaded until the packages loaded later are unloaded. Valid values include any, fifo, and lifo. FIFO loading is "first in, first out", which means packages picked up first must be dropped off first. LIFO is "last in, first out", which means packages picked up last must be dropped off first. The default value is any, which means there is no constraint on loading/unloading order for the vehicle.

Example request object - vehicles​

Services​

Services are locations that need to be visited, but these visits do not consume or relieve any capacity of the vehicle. For example, a plumber performing house calls does not need to drop off or pick up any units.

Field Description
name Required. A unique name for a service. This could be an order ID or identifier generated by an upstream system.
location Required. The location where a service is to be performed. This value should be the same as the value defined for the name field in locations.
duration Optional. The amount of time (integer seconds) the vehicle needs to stop at a location to complete the service.
requirements Optional. What capabilities are required at a location. Only vehicles that have these capabilities can do this service. You set the values related to requirements.
service_times Optional. Define when a service can start and when it must be finished. This is useful when a location is only accessible at certain times, or when an appointment has been arranged. An array of objects with earliest (timestamp string) and latest (timestamp string) required. Set type with one of the following values to define how strictly the time range needs to be adhered to: strict (default), soft, soft_start, or soft_end. Setting this value to soft allows the service to occur outside the window, but an increasing penalty is applied the further from the window it gets. soft_end permits deliveries to be late (but not early) and soft_start permits deliveries to be early (but not late). If a service has a corresponding duration, your latest time limit should take this into account. For example, if a service takes 60 seconds to complete, and the latest value is 19:00:00, the driver has to arrive by 18:59:00 to meet the constraint. Maximum of 1 service time may be supplied.

Example request objects - services​

Shipments​

Shipments are the items that need to be picked up at one location and delivered to another. Shipments have dimensions like size, weight, and units), and they consume capacity in the vehicles that carry them.

Field Description
name Required. A unique name for a shipment. This could be an order ID or identifier generated by an upstream system.
from Required. The location where the shipment must be picked up. This value must be the same as a value defined for the name field in locations.
to Required. The location where the location must be delivered. This value must be the same as a value defined for the name field in locations.
size Optional. How many units of capacity a shipment consumes in a vehicle. The units are released at the drop off location. A vehicle must have all the capacity units defined to do a pickup/drop off.
requirements Optional. Capabilities that a vehicle needs to do a pickup/drop off.
pickup_duration Optional. How long it takes to do the pickup. The default value is 0.
dropoff_duration Optional. How long it takes to do the drop off. The default value is 0.
pickup_times Optional. Define the time ranges when it is possible to do the pickup. Maximum of 1 pickup time window may be supplied.
dropoff_times Optional. Define the time ranges when it is possible to do the drop off. Maximum of 1 drop off time window may be supplied.

Example request object - shipments​

Options​

Optional. This object enables you to choose how to solve your routing problem.

Field Description
objectives Optional. An array of length 1 where can specify one of two routing objectives: minimize the total time traveled by the fleet (min-total-travel-duration), or minimize the length of the longest schedule in the fleet (min-schedule-completion-time). In practice, min-schedule-completion-time also improves shipment delivery times and increases fleet use by splitting routes when extra capacity is available. You may only specify one of these objectives.

Example request object - options​

Solution document​

Overview​

The root document has two elements: any shipments or services that are not included in the solution, and the routes for each vehicle.

Dropped​

This property lists shipments and services that are not included in the solution. This can occur when the optimization engine cannot find a solution, but by dropping a shipment or service from consideration, the engine can find a solution. If all shipments and services are solved, these lists are empty.

Routes​

A route is a sequence of stops to be visited by a single vehicle. The vehicle property is the name of the vehicle as defined in your routing problem document. The stops array describes the list and order of stops that the vehicle for the route should visit.

Field Description
type Required. The kind of stop for each location. Valid values include start, service, pickup, dropoff, break, and end.
location Required. The name of the location where a stop occurs.
eta Required. The expected time of arrival at a location.
odometer Required. How far you should have traveled when you arrive at this stop. Not present on break type stops.
wait Optional. How long you should wait before proceeding to the next stop. This value is >0 when you are scheduled to arrive too early for the next stop's service time range. Not present on end type stops.
duration Optional. How long a vehicle needs to stop at a location to complete the service. The duration of a stop is measured in seconds.

For stops of type service, pickup, and dropoff, there is an extra field called services, pickups, or dropoffs. This field contains an array of the names of the services, pickups, or deliveries to be completed at that location, in the order they should be completed.

Example stop​

Example solution​

Optimization v2 API errors​

Response body code HTTP status code Description
OK 200 The solution has been posted. The body of the HTTP response is the solution JSON document.
Accepted 202 The problem was submitted successfully. The id should be saved so that you can retrieve the solution.
Unauthorized 401 YOUR_MAPBOX_ACCESS_TOKEN is not valid. Your account might not have the needed permissions to access the Optimization v2 API. If you are interested in early access to the Optimization v2 API Beta, sign up here.
Not found 404 No submission was found that belongs to the account linked to the access token used. Check the id and your account token before trying again.
Unacceptable 422 The request is not formatted properly.

Optimization v2 API restrictions and limits​

If you require a higher rate limit,contact us.

Additional Developer Resources