Navigation service

This documentation is for v5 of the Directions API. For information about the earlier version, see the v4 documentation.

The Mapbox Directions API will show you how to get where you're going. With the Directions API, you can:

• Calculate optimal driving, walking, and cycling routes using traffic- and incident-aware routing
• Produce turn-by-turn instructions
• Produce routes with up to 25 coordinates anywhere on earth

This API supports 4 different routing profiles:

Retrieve directions between waypoints. Directions requests must specify at least two waypoints as starting and ending points.

Try this in the API Playground.

You can further refine the results from this endpoint with the following optional parameters:

Unrecognized options in the query string result in an InvalidInput error.

Example request

# Request directions with no additional options

$ curl "https://api.mapbox.com/directions/v5/mapbox/cycling/-122.42,37.78;-77.03,38.91?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request directions with radiuses and a polyline6 response through multiple waypoints

$ curl "https://api.mapbox.com/directions/v5/mapbox/driving/13.43,52.51;13.42,52.5;13.41,52.5?radiuses=40;;100&geometries=polyline6&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Specify bearings and radiuses

$ curl "https://api.mapbox.com/directions/v5/mapbox/driving/13.43,52.51;13.42,52.5;13.43,52.5?bearings=60,45;;45,45&radiuses=100;100;100&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request a route that approaches the destination on the curb of the driving side

$ curl "https://api.mapbox.com/directions/v5/mapbox/driving/13.43,52.51;13.43,52.5?approaches=unrestricted;curb&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request directions with voice and banner instructions specifying waypoint_names

$ curl "https://api.mapbox.com/directions/v5/mapbox/cycling/-122.42,37.78;-77.03,38.91?steps=true&voice_instructions=true&banner_instructions=true&voice_units=imperial&waypoint_names=Home;Work&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Retrieve directions response

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

Example response object

{
  "routes": [
    {
      "geometry": "mnn_Ick}pAfBiF`CzA",
      "legs": [
        {
          "summary": "Köpenicker Straße, Engeldamm",
          "weight": 44.4,
          "duration": 26.2,
          "steps": [
            {
              "intersections": [
                {
                  "out": 0,
                  "entry": [ true ],
                  "bearings": [ 125 ],
                  "location": [ 13.426579, 52.508068 ]
                },
                {
                  "out": 1,
                  "in": 2,
                  "entry": [ true, true, false ],
                  "bearings": [ 30, 120, 300 ],
                  "location": [ 13.426688, 52.508022 ]
                }
              ],
              "driving_side": "right",
              "geometry": "mnn_Ick}pAHUlAqDNa@",
              "mode": "driving",
              "maneuver": {
                "bearing_after": 125,
                "bearing_before": 0,
                "location": [ 13.426579, 52.508068 ],
                "modifier": "right",
                "type": "depart",
                "instruction": "Head southeast on Köpenicker Straße (L 1066)"
              },
              "ref": "L 1066",
              "weight": 35.9,
              "duration": 17.7,
              "name": "Köpenicker Straße (L 1066)",
              "distance": 98.1,
              "voiceInstructions": [
                {
                  "distanceAlongGeometry": 98.1,
                  "announcement": "Head southeast on Köpenicker Straße (L 1066), then turn right onto Engeldamm",
                  "ssmlAnnouncement": "<speak><amazon:effect name=\"drc\"><prosody rate=\"1.08\">Head southeast on Köpenicker Straße (L <say-as interpret-as=\"address\">1066</say-as>), then turn right onto Engeldamm</prosody></amazon:effect></speak>"
                },
                {
                  "distanceAlongGeometry": 83.1,
                  "announcement": "Turn right onto Engeldamm, then you will arrive at your destination",
                  "ssmlAnnouncement": "<speak><amazon:effect name=\"drc\"><prosody rate=\"1.08\">Turn right onto Engeldamm, then you will arrive at your destination</prosody></amazon:effect></speak>"
                }
              ],
              "bannerInstructions": [
                {
                  "distanceAlongGeometry": 98.1,
                  "primary": {
                    "text": "Engeldamm",
                    "components": [ { "text": "Engeldamm" } ],
                    "type": "turn",
                    "modifier": "right"
                  },
                  "secondary": null,
                  "then": null
                }
              ]
            },
            {
              "intersections": [
                {
                  "out": 2,
                  "in": 3,
                  "entry": [ false, true, true, false ],
                  "bearings": [ 30, 120, 210, 300 ],
                  "location": [ 13.427752, 52.50755 ]
                }
              ],
              "driving_side": "right",
              "geometry": "ekn_Imr}pARL\\T^RHDd@\\",
              "mode": "driving",
              "maneuver": {
                "bearing_after": 202,
                "bearing_before": 125,
                "location": [ 13.427752, 52.50755 ],
                "modifier": "right",
                "type": "turn",
                "instruction": "Turn right onto Engeldamm"
              },
              "weight": 8.5,
              "duration": 8.5,
              "name": "Engeldamm",
              "distance": 78.6,
              "voiceInstructions": [
                {
                  "distanceAlongGeometry": 27.7,
                  "announcement": "You have arrived at your destination",
                  "ssmlAnnouncement": "<speak><amazon:effect name=\"drc\"><prosody rate=\"1.08\">You have arrived at your destination</prosody></amazon:effect></speak>"
                }
              ],
              "bannerInstructions": [
                {
                  "distanceAlongGeometry": 78.6,
                  "primary": {
                    "text": "You will arrive at your destination",
                    "components": [ { "text": "You will arrive at your destination" } ],
                    "type": "arrive",
                    "modifier": "straight"
                  },
                  "secondary": {
                    "text": "Engeldamm",
                    "components": [ { "text": "Engeldamm" } ],
                    "type": "arrive",
                    "modifier": "straight"
                  }
                },
                {
                  "distanceAlongGeometry": 15,
                  "primary": {
                    "text": "You have arrived at your destination",
                    "components": [ { "text": "You have arrived at your destination" } ],
                    "type": "arrive",
                    "modifier": "straight"
                  },
                  "secondary": {
                    "text": "Engeldamm",
                    "components": [ { "text": "Engeldamm" } ]
                  }
                }
              ]
            },
            {
              "intersections": [
                {
                  "in": 0,
                  "entry": [ true ],
                  "bearings": [ 25 ],
                  "location": [ 13.427292, 52.506902 ]
                }
              ],
              "driving_side": "right",
              "geometry": "cgn_Iqo}pA",
              "mode": "driving",
              "maneuver": {
                "bearing_after": 0,
                "bearing_before": 205,
                "location": [ 13.427292, 52.506902 ],
                "type": "arrive",
                "instruction": "You have arrived at your destination"
              },
              "weight": 0,
              "duration": 0,
              "name": "Engeldamm",
              "distance": 0,
              "voiceInstructions": [ ],
              "bannerInstructions": [ ]
            }
          ],
          "distance": 176.7
        }
      ],
      "weight_name": "routability",
      "weight": 44.4,
      "duration": 26.2,
      "distance": 176.7
    }
  ],
  "waypoints": [
    {
      "name": "Köpenicker Straße",
      "location": [ 13.426579, 52.508068 ]
    },
    {
      "name": "Engeldamm",
      "location": [ 13.427292, 52.506902 ]
    }
  ],
  "code": "Ok",
  "uuid": "cjd51uqn5005447p8nte2zc4w"
}

The response body of a Directions API query contains a waypoint object, the input coordinates snapped to the roads network. A waypoint object contains the following properties:

Example waypoint object

{
    "name": "Kirkjubøarvegur",
    "location": [ -6.80897, 62.000075 ]
}

The response body of a Directions API query also contains an array of route objects. A route object describes a route through multiple waypoints. A route object contains the following properties:

Example route object

{
    "duration": 88.4,
    "distance": 830.4,
    "weight": 88.4,
    "weight_name": "routability",
    "geometry": "oklyJ`{ph@yBuY_F{^_FxJoBrBs@d@mAT",
    "legs": [ ],
    "voiceLocale": "en"
}

A route object contains a nested route leg object for each leg of the journey, which is one fewer than the number of input coordinates. A route leg object contains the following properties:

Example route leg object

{
    "annotation": {
        "distance": [
            4.294596842089401,
            5.051172053200946,
            5.533254065167979,
            6.576513793849532,
            7.4449640160938015,
            8.468757534990829,
            15.202780313562714,
            7.056346577326572
        ],
        "duration": [
            1,
            1.2,
            2,
            1.6,
            1.8,
            2,
            3.6,
            1.7
        ],
        "speed": [
            4.3,
            4.2,
            2.8,
            4.1,
            4.1,
            4.2,
            4.2,
            4.2
        ],
        "congestion": [
            "low",
            "moderate",
            "moderate",
            "moderate",
            "heavy",
            "heavy",
            "heavy",
            "heavy"
        ]
    },
    "duration": 14.3,
    "weight": 14.3,
    "distance": 53.4,
    "steps": [],
    "summary": ""
}

In a route leg object, a nested route step object includes one step maneuver object as well as information about travel to the following route step:

Example route step object

{
    "intersections": [
      {
        "out": 1,
        "location": [ 13.424671, 52.508812 ],
        "bearings": [ 120, 210, 300 ],
        "entry": [ false, true, true ],
        "in": 0,
        "lanes": [
          {
            "valid": true,
            "indications": [ "left" ]
          },
          {
            "valid": true,
            "indications": [ "straight" ]
          },
          {
            "valid": false,
            "indications": [ "right" ]
          }
        ]
      }
    ],
    "geometry": "asn_Ie_}pAdKxG",
    "maneuver": {
      "bearing_after": 202,
      "type": "turn",
      "modifier": "left",
      "bearing_before": 299,
      "location": [ 13.424671, 52.508812 ],
      "instruction": "Turn left onto Adalbertstraße"
    },
    "duration": 59.1,
    "distance": 236.9,
    "driving_side": "right",
    "weight": 59.1,
    "name": "Adalbertstraße",
    "mode": "driving"
}

A route step object contains a nested step maneuver object, which contains the following properties:

• If no modifier is provided, the type of maneuvers is limited to depart and arrive.
• If the source or target location is close enough to the depart or arrive location, no modifier will be given.

Maneuver types

Note: New properties (potentially depending on type) may be introduced in the future without an API version change.

Example step maneuver object

{
    "bearing_before": 299,
    "bearing_after": 202,
    "type": "turn",
    "modifier": "left",
    "location": [ 13.424671, 52.508812 ],
    "instruction": "Turn left onto Adalbertstraße"
}

A route step object contains a nested lane object. The lane object describes the available turn lanes at an intersection. Lanes are provided in their order on the street, from left to right.

Example lane object

{
    "valid": true,
    "indications": [
        "left"
    ]
}

A route step object contains a nested voice instruction object if the optional voice_instructions=true query parameter is present. The voice instruction object contains the text that should be announced, along with how far from the maneuver it should be emitted. The voice instructions are children of the route step during which they should be spoken, but they refer to the maneuver in the following step.

Example voice instruction object

{
    "distanceAlongGeometry": 375.7,
    "announcement": "In a quarter mile, take the ramp on the right towards I 495: Baltimore",
    "ssmlAnnouncement": "<speak><amazon:effect name=\"drc\"><prosody rate=\"1.08\">In a quarter mile, take the ramp on the right towards <say-as interpret-as=\"address\">I-495</say-as>: Baltimore</prosody></amazon:effect></speak>"
}

A route step object contains a nested banner instruction object if the optional banner_instructions=true query parameter is present. The banner instruction object contains the contents of a banner that should be displayed as added visual guidance for a route. The banner instructions are children of the route steps during which they should be displayed, but they refer to the maneuver in the following step.

Each of the different banner types (primary, secondary, and sub) contains the following properties:

Abbreviation examples

Given the components in the table above, the possible abbreviations are, in order:

• North Franklin Dr
• N Franklin Dr

Example banner instruction object

{
    "distanceAlongGeometry": 100,
    "primary": {
        "type": "turn",
        "modifier": "left",
        "text": "I 495 North / I 95",
        "components": [
          {
            "text": "I 495",
            "imageBaseURL": "https://s3.amazonaws.com/mapbox/shields/v3/i-495",
            "type": "icon"
          },
          {
            "text": "North",
            "type": "text",
            "abbr": "N",
            "abbr_priority": 0
          },
          {
            "text": "/",
            "type": "delimiter"
          },
          {
            "text": "I 95",
            "imageBaseURL": "https://s3.amazonaws.com/mapbox/shields/v3/i-95",
            "type": "icon"
          }
        ]
    },
    "secondary": {
        "type": "turn",
        "modifier": "left",
        "text": "Baltimore / Northern Virginia",
        "components": [
          {
            "text": "Baltimore",
            "type": "text"
          },
          {
            "text": "/",
            "type": "text"
          },
          {
            "text": "Northern Virginia",
            "type": "text"
          }
      ]
    },
    "sub": {
        "text": "",
        "components": [
          {
            "text": "",
            "type": "lane",
            "directions": ["left"],
            "active": true
          },
          {
            "text": "",
            "type": "lane",
            "directions": ["left", "straight"],
            "active": true
          },
          {
            "text": "",
            "type": "lane",
            "directions": ["right"],
            "active": false
          }
        ]
    }
}

The table below shows supported language codes used with the language parameter for turn-by-turn instructions. The language parameter will automatically be set to en (English) if an unsupported language code is used.

On error, the server responds with different HTTP status codes. For responses with HTTP status codes lower than 500, the JSON response body includes the code property, which may be used by client programs to manage control flow. The response body may also include a message property with a human-readable explanation of the error.

If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

• Requests using the driving, walking, and cycling profiles can specify up to 25 total waypoints (input coordinates that are snapped to the roads network) along the route.
• Requests using the driving-traffic profile can specify up to 3 waypoints along the route.
• Traffic coverage for the driving-traffic profile is available in supported geographies. Requests to this profile revert to driving profile results for areas without traffic coverage.
• Maximum 300 requests per minute.
• Maximum total of 10,000 kilometers between all waypoints.

An isochrone, from the Greek root words iso (equal) and chrone (time), is a line that connects points of equal travel time around a given location. The Mapbox Isochrone API computes areas that are reachable within a specified amount of time from a location, and returns the reachable regions as contours of polygons or lines that you can display on a map.

Given a location and a routing profile, retrieve up to four isochrone contours. The contours are calculated using rasters and are returned as either polygon or line features, depending on your input setting for the polygons parameter.

You can further refine the results from this endpoint with the following optional parameters:

Example request

$ curl "https://api.mapbox.com/isochrone/v1/mapbox/driving/-118.22258,33.99038?contours_minutes=5,10,15&contours_colors=6706ce,04e813,4286f4&polygons=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Retrieve isochrones response

In the response to a request to the Mapbox Isochrone API, the isochrone contours are returned as a GeoJSON Feature Collection. Each feature object in the Feature Collection is an isochrone, and contains the following properties:

Example response

{
    "features": [
        {
            "properties": {
                "contour": 15,
                "color": "#4286f4",
                "opacity": 0.33,
                "fill": "#4286f4",
                "fill-opacity": 0.33,
                "fillColor": "#4286f4",
                "fillOpacity": 0.33
            },
            "type": "Feature",
            "geometry": {
                "coordinates": [ "arrays of longitude, latitude coordinates" ],
                "type": "Polygon"
            }
        },
        {
            "properties": {
                "contour": 10,
                "color": "#04e813",
                "opacity": 0.33,
                "fill": "#04e813",
                "fill-opacity": 0.33,
                "fillColor": "#04e813",
                "fillOpacity": 0.33
            },
            "type": "Feature",
            "geometry": {
                "coordinates": [ "arrays of longitude, latitude coordinates" ],
                "type": "Polygon"
            }
        },
        {
            "properties": {
                "contour": 5,
                "color": "#6706ce",
                "opacity": 0.33,
                "fill": "#6706ce",
                "fill-opacity": 0.33,
                "fillColor": "#6706ce",
                "fillOpacity": 0.33
            },
            "type": "Feature",
            "geometry": {
                "coordinates": [ "arrays of longitude, latitude coordinates" ],
                "type": "Polygon"
            }
        }
    ],
    "type": "FeatureCollection"
}

• The Isochrone API is limited to 300 requests per minute.
• The Isochrone API supports one coordinate per request.
• The Isochrone API can support a maximum of 4 isochrone contours per request.
• The maximum time that can be specified for an isochrone contour is 60 minutes.
• Results must be displayed on a Mapbox map using one of the Mapbox libraries or SDKs.

If you require a higher rate limit, contact us.

This documentation is for v5 of the Map Matching API. For information about the earlier version, see the v4 documentation.

The Mapbox Map Matching API snaps fuzzy, inaccurate traces from a GPS unit or a phone to the OpenStreetMap road and path network using the Directions API. This produces clean paths that can be displayed on a map or used for other analysis. The Map Matching API can also return a full directions response to queries.

Return a path on the road and path network that is closest to the input traces.

You can further refine the results from this endpoint with the following optional parameters:

Some pre-processing tips to achieve the best results:

• Timestamps improve the quality of the matching and are highly recommended.
• The Map Matching API is limited to processing traces with up to 100 coordinates. If you need to process longer traces, you can split the trace and make multiple requests.
• Clusters of points (like a person waiting at a train crossing for a few minutes) often don't add more information to a trace and can negatively impact map-matching quality. We recommend that you tidy the trace (remove clusters and provide a uniform sample rate). You can use the tidy=true query parameter or pre-process your traces with external tools like geojson-tidy.
• Map matching works best with a sample rate of 5 seconds between points. If your trace has a higher sample rate, you may want to downsample your trace.
• With the waypoints parameter specified, traces that would normally return with sub-matches will error. We recommend tidying traces before using them with the waypoints parameter.

Example request

# Basic request that returns a match object with route legs between each waypoint

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/-117.17282,32.71204;-117.17288,32.71225;-117.17293,32.71244;-117.17292,32.71256;-117.17298,32.712603;-117.17314,32.71259;-117.17334,32.71254?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request with the approaches parameter set to 'curb' for each waypoint

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/-117.17282,32.71204;-117.17288,32.71225;-117.17293,32.71244;-117.17292,32.71256?approaches=curb;curb;curb;curb&access_token=YOUR_MAPBOX_ACCESS_TOKEN"


# Request with various parameters, returns a match object with 1 route leg between the first and last waypoints

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/2.344003,48.85805;2.34675,48.85727;2.34868,48.85936;2.34955,48.86084;2.34955,48.86088;2.34962,48.86102;2.34982,48.86125?steps=true&tidy=true&waypoints=0;6&waypoint_names=Home;Work&banner_instructions=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Retrieve a match response

The match response object contains one or more match objects, as well as one or more tracepoint objects.

With clean matches, only one match object is returned. When the the algorithm cannot decide the correct match between two points, it will omit that line and return several sub-matches as match objects. The higher the number of sub-match match objects, the more likely it is that the input traces are poorly aligned to the road network.

With clean matches, only one match object is returned. When the the algorithm cannot decide the correct match between two points, it will omit that line and return several sub-matches as match objects. The higher the number of sub-match match objects, the more likely it is that the input traces are poorly aligned to the road network.

Example match response object

{
  "matchings": [
    {
      "confidence": 0.9857403441039709,
      "geometry": "gatfEfidjUk@Lc@@Y?",
      "legs": [
        {
          "summary": "",
          "weight": 2.7,
          "duration": 2.7,
          "steps": [],
          "distance": 25
        },
        {
          "summary": "",
          "weight": 2.4,
          "duration": 2.4,
          "steps": [],
          "distance": 21
        },
        {
          "summary": "",
          "weight": 1.6,
          "duration": 1.6,
          "steps": [],
          "distance": 14
        }
      ],
      "weight_name": "routability",
      "weight": 6.699999999999999,
      "duration": 6.699999999999999,
      "distance": 60
    }
  ],
  "tracepoints": [
    {
      "alternatives_count": 0,
      "waypoint_index": 0,
      "matchings_index": 0,
      "name": "North Harbor Drive",
      "location": [
        -117.172836,
        32.712041
      ]
    },
    {
      "alternatives_count": 0,
      "waypoint_index": 1,
      "matchings_index": 0,
      "name": "North Harbor Drive",
      "location": [
        -117.17291,
        32.712256
      ]
    },
    {
      "alternatives_count": 0,
      "waypoint_index": 2,
      "matchings_index": 0,
      "name": "North Harbor Drive",
      "location": [
        -117.17292,
        32.712444
      ]
    },
    {
      "alternatives_count": 9,
      "waypoint_index": 3,
      "matchings_index": 0,
      "name": "North Harbor Drive",
      "location": [
        -117.172922,
        32.71257
      ]
    }
  ],
  "code": "Ok"
}

A match object is a route object with an additional confidence field:

Example match object

{
    "confidence": 0.9548844020537051,
    "distance": 103.7,
    "duration": 16.4,
    "geometry": "gatfEfidjUi@Le@@Y?E??J?^Hf@",
    "legs": []
}

A tracepoint object is a waypoint object with 3 additional fields: matchings_index, waypoint_index, and alternatives_count.

Example tracepoint object

{
    "waypoint_index": 0,
    "location": [-117.172836, 32.71204],
    "name": "North Harbor Drive",
    "matchings_index": 0,
    "alternatives_count": 0
}

The Map Matching API supports access via the HTTP POST method. To submit a request using HTTP POST, you must make the following changes to the request:

1. The HTTP method must be POST
2. The Content-Type of the request must be application/x-www-form-urlencoded
3. The coordinate list must be present in the request body as the coordinates= parameter, and there must be no coordinates in the URL
4. The access_token parameter must be part of the POST URL, not the body
5. All other parameters must be part of the request body

An example POST request looks like this:

POST /matching/v5/mapbox/driving?access_token={your_access_token} HTTP/1.0
Content-Type: application/x-www-form-urlencoded

coordinates=2.344003915786743,48.85805170891599;2.346750497817993,48.85727523615161;2.348681688308716,48.85936462637049;2.349550724029541,48.86084691113991;2.349550724029541,48.8608892614883;2.349625825881958,48.86102337068847;2.34982967376709,48.86125629633996&steps=true&tidy=true&waypoints=0;6

# Basic request using POST interface

$ curl -d "coordinates=-117.17282,32.71204;-117.17288,32.71225;-117.17293,32.71244;-117.17292,32.71256;-117.17298,32.712603;-117.17314,32.71259;-117.17334,32.71254"
"https://api.mapbox.com/matching/v5/mapbox/driving?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request with various parameters, will return a match object with one route leg between the first and last waypoints

$ curl -d "coordinates=2.344003,48.85805;2.34675,48.85727;2.34868,48.85936;2.34955,48.86084;2.34955,48.86088;2.349625,48.86102;2.34982,48.86125&steps=true&tidy=true&waypoints=0;6&waypoint_names=Home;Work&banner_instructions=true" "https://api.mapbox.com/matching/v5/mapbox/driving?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

On error, the server responds with different HTTP status codes.

• For responses with HTTP status codes lower than 500, the JSON response body includes the code property, which may be used by client programs to manage control flow. The response body may also include a message property, with a human-readable explanation of the error.
• If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

• The Map Matching API is limited to 300 requests per minute.
• Each request can have a maximum of 100 coordinates.
• Results must be displayed on a Mapbox map using one of the Mapbox libraries or SDKs.

For high volume or other use cases, contact us.

The Mapbox Matrix API returns travel times between many points.

For example, given 3 locations A, B, and C, the Matrix API will return a matrix of all travel times in seconds between the locations:

The Matrix API will always return the duration or the distance on the fastest route for each element in the matrix, where an element is an origin-destination pair in the matrix. The Matrix API returns durations in seconds and distances in meters. It does not return route geometries.

Durations or distances between points may not be symmetric, since the routes may differ by direction due to one-way streets or turn restrictions. For example, A to B may have a different duration than B to A.

The Matrix API allows you to efficiently check the reachability of coordinates from each other, filter points by travel time, or run your own algorithms for solving optimization problems.

Returns a duration matrix, a distance matrix, or both, showing travel times and distances between coordinates. In the default case, this endpoint returns a symmetric matrix that uses all the input coordinates as sources and destinations. Using the optional sources and destination parameters, you can also generate an asymmetric matrix that uses only some coordinates as sources or destinations.

You can further refine the results from this endpoint with the following optional parameters:

Unrecognized options in the query string will result in an InvalidInput error.

Example requests

# Request a symmetric 3x3 matrix for cars with a curbside approach for each destination

$ curl "https://api.mapbox.com/directions-matrix/v1/mapbox/driving/-122.42,37.78;-122.45,37.91;-122.48,37.73?approaches=curb;curb;curb&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request an asymmetric 2x3 matrix for bicycles

$ curl "https://api.mapbox.com/directions-matrix/v1/mapbox/cycling/-122.42,37.78;-122.45,37.91;-122.48,37.73?sources=0;2&destinations=all&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request a 1x3 matrix for walking that includes both duration and distance

$ curl "https://api.mapbox.com/directions-matrix/v1/mapbox/walking/-122.418563,37.751659;-122.422969,37.75529;-122.426904,37.759617?sources=1&annotations=distance,duration&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Retrieve a matrix response

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

Note: If no route is found between a source and a destination, the respective value in the durations or distances matrix will be null.

Example response

{
    "code": "Ok",
    "durations": [
        [ 0,      573, 1169.5 ],
        [ 573,    0,      597 ],
        [ 1169.5, 597,      0 ]
    ],
    "destinations": [
        {
            "name": "Mission Street",
            "location": [ -122.418408, 37.751668 ]
        },
        {
            "name": "22nd Street",
            "location": [ -122.422959, 37.755184 ]
        },
        {
            "name": "",
            "location": [ -122.426911, 37.759695 ]
        }
    ],
    "sources": [
        {
            "name": "Mission Street",
            "location": [ -122.418408, 37.751668 ]
        },
        {
            "name": "22nd Street",
            "location": [ -122.422959, 37.755184 ]
        },
        {
            "name": "",
            "location": [ -122.426911, 37.759695 ]
        }
    ]
}

On error, the server responds with different HTTP status codes. For responses with HTTP status codes lower than 500, the JSON response body includes the code property, which may be used by client programs to manage control flow. The response body may also include a message property with a human-readable explanation of the error.

In the case of a server error, the HTTP status code will be 500 or higher and the response will not include a code property.

In cases where no route is found between a source and a destination, no error will be returned. Instead, the respective value in the durations or distances matrix will be null.

• For the mapbox/driving, mapbox/walking, and mapbox/cycling profiles:

  • Maximum 25 input coordinates per request
  • Maximum 300 requests per minute

• For the mapbox/driving-traffic profile:

  • Maximum 10 input coordinates per request
  • Maximum 300 requests per minute

For higher volumes, contact us.

The Mapbox Optimization API returns a duration-optimized route between the input coordinates. This is also known as solving the Traveling Salesperson Problem. A typical use case for the Optimization API is planning the route for deliveries in a city. You can retrieve a route for car driving, bicycling, and walking.

A call to this endpoint retrieves a duration-optimized route between input coordinates.

You can further refine the results from this endpoint with the following optional parameters:

Unrecognized options in the query string result in an InvalidInput error.

Note that routes returned by the Optimization API will behave as if continue_straight=false was set at each waypoint, meaning that the route will continue in the same direction of travel. See the continue_straight parameter in the Directions API for more details on what this means for the route.

Fixing Start and End Points

It is possible to explicitly set the start or end coordinate of the trip:

• When source=first, the first coordinate is used as the start coordinate of the trip in the output.
• When destination=last, the last coordinate is used as the destination coordinate of the trip in the output.
• If you specify any for source or destination, any of the coordinates can be used as the first or last coordinate in the output.
• If source=any&destination=any, the returned roundtrip will start at the first input coordinate by default.

Not all combinations of roundtrip, source, and destination are supported. Right now, the following combinations are possible:

Example request

# Request an optimized car trip with no additional options

$ curl "https://api.mapbox.com/optimized-trips/v1/mapbox/driving/-122.42,37.78;-122.45,37.91;-122.48,37.73?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request an optimized bicycle trip with steps and a GeoJSON response

$ curl "https://api.mapbox.com/optimized-trips/v1/mapbox/cycling/-122.42,37.78;-122.45,37.91;-122.48,37.73?steps=true&geometries=geojson&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request an optimized car roundtrip in Berlin with four coordinates, starting at the first coordinate pair and ending at the last coordinate pair

$ curl "https://api.mapbox.com/optimized-trips/v1/mapbox/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219;13.418555,52.523215?source=first&destination=last&roundtrip=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request an optimized car trip with four coordinates and one distributions constraint where the last given coordinate must be visited before the second

$ curl "https://api.mapbox.com/optimized-trips/v1/mapbox/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219;13.418555,52.523215?roundtrip=true&distributions=3,1&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request an optimized car trip with specified waypoint approach bearings and turn-by-turn instructions

$ curl "https://api.mapbox.com/optimized-trips/v1/mapbox/driving/-122.42,37.78;-122.45,37.91;-122.48,37.73?radiuses=unlimited;unlimited;unlimited&bearings=45,90;90,1;340,45&steps=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Retrieve an optimization response

The response to an Optimization API request is a JSON object that contains the following properties:

Waypoint objects

A waypoint object is an input coordinate snapped to the roads network that contains the following properties:

Trip object

A trip object describes a route through multiple waypoints, and has the following properties:

A trip object has the same format as a route object in the Directions API.

Example response object

{
    "code": "Ok",
    "waypoints": [
        {
            "name": "North Lake Boulevard",
            "location": [ -120.141159, 39.170872 ],
            "waypoint_index": 0,
            "trips_index": 0
        },
        {
            "name": "Virginia Drive",
            "location": [ -120.14984, 39.159985 ],
            "waypoint_index": 2,
            "trips_index": 0
        },
        {
            "name": "Fairway Drive",
            "location": [ -120.150648, 39.340689 ],
            "waypoint_index": 1,
            "trips_index": 0
        }
    ],
    "trips": [
        {
            "geometry": "}panFfah|Ujj@ru@`Dp`BwNdpAwc@pw@ibAxm@snA|Ic^|\\q{@{S}`@lVewBzUa}@t^}oAdEkbB}[{AvHqdDs\\qn@lV_OqpA{`A}bBaRucA_gB}eCbI_MzXzY`Va]xUbPzE|[{E}[_WoP{Tl]{X{YoLfQtjBvdCbRpcA|_A|`BbD`qA~y@{WpdDr\\z{AwHh}A`\\hsA{Dv~@c_@dwB{U|`@mVp{@zSfe@_`@niA}G|aAin@~b@mx@|LunBsBw}@{Sia@bp@nDcCpYbCqYou@uDsP_U",
            "legs": [
                {
                    "summary": "",
                    "weight": 1962.8,
                    "duration": 1876.9,
                    "steps": [],
                    "distance": 31507.9
                },
                {
                    "summary": "",
                    "weight": 2211.9,
                    "duration": 2035.1,
                    "steps": [],
                    "distance": 32720.5
                },
                {
                    "summary": "",
                    "weight": 283.5,
                    "duration": 238.1,
                    "steps": [],
                    "distance": 1885.2
                }
            ],
            "weight_name": "routability",
            "weight": 4458.2,
            "duration": 4150.1,
            "distance": 66113.6
        }
    ]
}

On error, the server responds with different HTTP status codes. For responses with HTTP status codes lower than 500, the JSON response body includes the code property, which may be used by client programs to manage control flow. The response body may also include a message property with a human-readable explanation of the error.

If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

All other properties might be undefined.

• Maximum 12 coordinates per request
• Maximum 25 distributions per request
• Maximum 300 requests per minute

For higher volumes, contact us.