# Directions Matrix

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

```python >>> from mapbox import DirectionsMatrix

```

See https://www.mapbox.com/api-documentation/navigation/#matrix for general documentation of the API.

Your Mapbox access token should be set in your environment; see the [access tokens](access_tokens.md) documentation for more information.

## DirectionsMatrix methods

DirectionsMatrix methods return an instance of [requests.Response](http://docs.python-requests.org/en/latest/api/#requests.Response). If the response is successful, the json() method returns Python data parsed directly from the API.

## Usage

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.

```python >>> service = DirectionsMatrix()

```

The input waypoints to the directions method are [features](input_features.md), typically GeoJSON-like feature dictionaries.

```python >>> 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.

```python >>> response = service.matrix([portland, bend, corvallis], profile=’mapbox/driving’) >>> response.status_code 200 >>> 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.

```python >>> from pprint import pprint >>> pprint(response.json()[‘durations’]) [[0.0, …, …], […, 0.0, …], […, …, 0.0]]

```

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