Optimization API v2
Mapbox is launching a Beta program for the Optimization v2 API with many new features, including time window constraints, vehicle capacity limits, driver shifts, and pickup and drop off constraints.If you are interested in early access to the Optimization v2 API Beta, sign up here.
This page documents the Optimization v2 API Beta functionality.If you would like to use the Optimization v1 here, documentation is available here.
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
POSTto/optimized-trips/v2?access_token=YOUR_MAPBOX_TOKENto submit a routing problem, and save theidfrom the JSON response.GETfrom/optimized-trips/v2/{id}?access_token=YOUR_MAPBOX_TOKENto check the status and receive the result when it is complete.GETfrom/optimized-trips/v2?access_token=YOUR_MAPBOX_TOKENto list all your account's submitted routing problems and their processing statuses.
Submit a routing problem
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
POST /optimized-trips/v2?access_token=YOUR_MAPBOX_ACCESS_TOKENHTTP/1.1
Host: api.mapbox.com
Content-Type: application/json
{
"version": 1,
"vehicles": [...],
"services": [...]
}
Example cURL request
$curl -H 'Content-Type: application/json'
-d @problem.json
'https://api.mapbox.com/optimized-trips/v2?access_token=YOUR_MAPBOX_ACCESS_TOKEN'
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:
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"id": "123e4567-e89b-12d3-a456-426655440000",
"status": "ok"
}
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.
To learn about other responses for this API, see Optimization v2 API errors.
Retrieve a solution
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
GET /optimized-trips/v2/123e4567-e89b-12d3-a456-426655440000?access_token=YOUR_MAPBOX_ACCESS_TOKEN
Content-Type: application/json
Host: api.mapbox.com
Example cURL request
$curl "https://api.mapbox.com/optimized-trips/v2/YOUR_JOB_ID?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
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.
{
"dropped": {
"services": [],
"shipments": []
},
"routes": [
{
"vehicle": "truck-1",
"stops": [
{
"location": "warehouse",
"eta": "2022-01-01T09:00:00Z",
"type": "start",
"wait": 0,
"odometer": 0
},
{
"location": "stop-3",
"eta": "2022-01-01T09:01:12Z",
"type": "dropoff",
"duration": 0,
"wait": 0,
"odometer": 381
},
{
"location": "stop-2",
"eta": "2022-01-01T09:01:36Z",
"type": "dropoff",
"duration": 0,
"wait": 0,
"odometer": 487
},
{
"location": "stop-1",
"eta": "2022-01-01T09:01:53Z",
"type": "dropoff",
"duration": 0,
"wait": 0,
"odometer": 587
},
{
"location": "warehouse",
"eta": "2022-01-01T09:02:28Z",
"type": "end",
"odometer": 762
}
]
}
]
}
List submissions and their status
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
GET /optimized-trips/v2?access_token=YOUR_MAPBOX_ACCESS_TOKEN
Content-Type: application/json
Host: api.mapbox.com
Example cURL request
$curl --request GET
--url 'https://api.mapbox.com/optimized-trips/v2?access_token=YOUR_MAPBOX_ACCESS_TOKEN'
--header 'Content-Type: application/json'
200 OK
You will receive a JSON response body that is structured as follows:
[
{ "id": "123e4567-e89b-12d3-a456-426655440000", "status": "processing" },
{ "id": "123e4567-e89b-12d3-a456-426655440001", "status": "complete" }
]
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
- All time values are in ISO 8601 format. For example,
2023-07-22T14:29:23.123-0700. Time zones are supported. Milliseconds are accepted, but ignored. - Duration values are in seconds.
- Distance values are in meters.
Overview
The root object in the routing problem document contains five elements:
{
"version": 1,
"locations": [...],
"vehicles": [...],
"services": [...],
"shipments": [...]
}
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
"locations": [
{
"name": "123 Address Street",
"coordinates": [ -122.1234, 37.812 ],
}
]
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
"vehicles": [
{
"name": "truck-1",
"routing_profile": "mapbox/driving",
"start_location": "warehouse",
"end_location": "warehouse",
"capacities": {
"volume": 3000,
"weight": 1000,
"boxes": 100
},
"capabilities": [
"ladder",
"refrigeration"
],
"earliest_start": "2022-05-31T09:00:00Z",
"latest_end": "2022-05-31T17:00:00Z",
"breaks": [
{
"earliest_start": "2022-05-31T12:00:00Z",
"latest_end": "2022-05-31T13:00:00Z",
"duration": 1800
}
]
}
]
Services
At least one of services or shipments is required to submit the routing
problem document. If you define services, then shipments is optional.
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
"services": [
{
"name": "work-order-1234",
"location": "123 Address Street",
"duration": 300,
"requirements": [
"ladder"
],
"service_times": [
{
"earliest": "2022-05-31T13:00:00Z",
"latest": "2022-05-31T14:00:00Z",
"type": "soft"
}
]
}
]
Shipments
At least one of shipments or services is required to submit the routing
problem document. If you define shipments, then services is optional.
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
"shipments": [
{
"name": "order-1234",
"from": "warehouse",
"to": "123 Address Street",
"size": {
"weight": 30,
"volume": 100,
"boxes": 3
},
"requirements": [
"refrigeration"
],
"pickup_duration": 60,
"dropoff_duration": 60,
"pickup_times": [
{
"earliest": "2022-05-31T09:15:00Z",
"latest": "2022-05-31T09:30:00Z",
"type": "strict"
}
],
"dropoff_times": [
{
"earliest": "2022-05-31T10:15:00Z",
"latest": "2022-05-31T10:30:00Z",
"type": "soft_end"
}
]
}]
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
"options": {
"objectives": ["min-schedule-completion-time"]
}
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": {
"shipments": [...],
"services": [...]
},
"routes": [
{
"vehicle": "name",
"stops": [...]
},
...
]
}
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
{
"type": "service",
"services": ["service-1"],
"location": "location-1",
"eta": "2022-08-02T09:15:00Z",
"odometer": 17.2,
"wait": 0
}
Example solution
{
"dropped": {
"services": ["service-3", "service-4"],
"shipments": []
},
"routes": [
{
"vehicle": "xyz",
"stops": [
{
"type": "depart",
"location": "warehouse",
"eta": "2022-08-02T09:00:00Z",
"odometer": 0
},
{
"type": "service",
"location": "location-1",
"services": ["service-1"],
"eta": "2022-08-02T14:42:00Z",
"odometer": 100,
"wait": 300
},
{ "type": "break", "eta": "2022-08-02T14:42:00Z", "wait": 3600 },
{
"type": "service",
"services": ["service-2"],
"location": "location-2",
"eta": "2022-08-02T15:42:00Z",
"wait": 0,
"odometer": 200
},
{
"type": "arrive",
"location": "warehouse",
"eta": "2022-08-02T20:24:00Z",
"odometer": 300
}
]
}
]
}
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
- Maximum of 300 routing problems submitted per minute
- Maximum of 60 list submissions requests per minute
- Maximum of 60 solutions status requests per minute
- Maximum number of 1000 locations per routing problem