Distance

This documentation is for the legacy Distance API. See the documentation for the current Mapbox Matrix API.

The Mapbox Distance API returns all travel times between many points.

For example, given 3 locations A, B, C, the Distance API will return a matrix of travel times in seconds between each location:

A B C
A A → A A → B A → C
B B → A B → B B → C
C C → A C → B C → C

This API allows you to build tools that efficiently check the reachability of coordinates from each other, filter points by travel time, or run algorithms for solving optimization problems.

Limits

  • Maximum 100 coordinate pairs per request
  • Maximum 60 requests per minute

For higher volumes, contact us.

Retrieve a duration matrix

Returns a duration matrix showing travel times between given locations.

POST /distances/v1/mapbox/{profile}

The {profile} parameter of your request should be a Mapbox Directions routing profile ID. The following IDs are supported:

  • driving for car travel times
  • walking for pedestrian and hiking travel times
  • cycling for bicycle travel times

Example Request

curl -X POST \
  --header "Content-Type:application/json" \
  -d @coordinates.json \
  "https://api.mapbox.com/distances/v1/mapbox/driving?access_token={your_access_token}"
>>> from mapbox import Distance
>>> service = Distance()
>>> service.distances([portland, bend, corvallis], 'driving')
var mapboxClient = new MapboxClient('{your_access_token}');

// With options
mapboxClient.getDistances([
  [-95.4431142, 33.6875431],
  [-95.0431142, 33.6875431],
  [-95.0431142, 33.0875431],
  [-95.0431142, 33.0175431],
  [-95.4831142, 33.6875431]
], {
  profile: 'walking'
}, function(err, results) {
  console.log(results);
});

// Results is an object like:
{ durations:
  [ [ 0, 1196, 3977, 3415, 5196 ],
    [ 1207, 0, 3775, 3213, 4993 ],
    [ 3976, 3774, 0, 2650, 2579 ],
    [ 3415, 3212, 2650, 0, 3869 ],
    [ 5208, 5006, 2579, 3882, 0 ] ] }
mapbox distance many_points.geojson
// This API cannot be accessed with the Mapbox Java SDK
// This API cannot be accessed with the Mapbox Objective-C libraries
// This API cannot be accessed with the Mapbox Swift libraries

Example request body

The Content-Type header of the request needs to be set to application/json.

{
  "coordinates": [
    ["A"],
    ["B"],
    ["C"]
  ]
}
{
  "coordinates": [
    [13.41894, 52.50055],
    [14.10293, 52.50055],
    [13.50116, 53.10293]
  ]
}
Property Description
coordinates an array of up to 100 [longitude, latitude] coordinate pairs

Example response

The Distance API returns an object that resembles a matrix, or table, of durations: the time it takes to get between two points on the shortest route in seconds. The order of durations in the response object is directly related to the order of coordinates in the request body.

The Distance API will always return the duration on the fastest route. Durations between points may not be symmetric, as the routes may differ by direction (for example, A to B may have a different duration than B to A). The Distance API only returns durations in seconds; it does not return route geometries.

The duration between the same coordinate is always 0. If a duration can not be found, the result is null. All values are in seconds.

{
  "durations": [
    ["A to A", "A to B", "A to C"],
    ["B to A", "B to B", "B to C"],
    ["C to A", "C to B", "C to C"]
  ]
}
{
  "durations": [
    [0,    2910, null],
    [2903, 0,    5839],
    [4695, 5745, 0   ]
  ]
}
Property Description
durations an array of arrays of durations in seconds