Directions Matrix

The DirectionsMatrix class from the module provides access to the Mapbox Matrix API V1. You can also import it directly from the mapbox module.

>>> from mapbox import DirectionsMatrix

See for general documentation of the API.

Your Mapbox access token should be set in your environment; see the access tokens documentation for more information.

DirectionsMatrix methods

DirectionsMatrix methods return an instance of requests.Response. If the response is successful, the json() method returns Python data parsed directly from the API.


If you need to optimize travel between several waypoints, you can use the Matrix API to create a matrix showing travel times between all waypoints. Each of your input waypoints should be a GeoJSON point feature, a GeoJSON geometry, or a (longitude, latitude) pair.

>>> service = DirectionsMatrix()

The input waypoints to the directions method are features, typically GeoJSON-like feature dictionaries.

>>> portland = {
...    'type': 'Feature',
...    'properties': {'name': 'Portland, OR'},
...    'geometry': {
...        'type': 'Point',
...        'coordinates': [-122.7282, 45.5801]}}
>>> bend = {
...    'type': 'Feature',
...    'properties': {'name': 'Bend, OR'},
...    'geometry': {
...        'type': 'Point',
...        'coordinates': [-121.3153, 44.0582]}}
>>> corvallis = {
...    'type': 'Feature',
...    'properties': {'name': 'Corvallis, OR'},
...    'geometry': {
...        'type': 'Point',
...        'coordinates': [-123.268, 44.5639]}}

The matrix method can be called with a list of point features and the travel profile.

>>> response = service.matrix([portland, bend, corvallis], profile='mapbox/driving')
>>> response.status_code
>>> response.headers['Content-Type']
'application/json; charset=utf-8'

And the response JSON contains a matrix, a 2-D list with travel times (seconds) between all input waypoints. The diagonal will be zeros.

>>> from pprint import pprint
>>> pprint(response.json()['durations'])
[[0.0, ..., ...], [..., 0.0, ...], [..., ..., 0.0]]

See import mapbox; help(mapbox.DirectionsMatrix) for more detailed usage.