Navigation service

The Mapbox Navigation service is composed of the following APIs:

    Using HTTP POST

    The Directions API and Map Matching API both support access using the HTTP POST method. HTTP POST should be used for large requests, since both the Directions and Map Matching APIs have a size limit of approximately 8100 bytes on GET request URLs. If you receive an HTTP 413 ("Request entity too large") or HTTP 414 ("Request URL too large") error when you make a GET request to either API, then using POST is a good option for you.

    To submit a request using HTTP POST, make the following changes to the request:

    • The HTTP method must be POST.
    • The Content-Type of the request must be application/x-www-form-urlencoded.
    • The coordinate list must be present in the request body as the coordinates= parameter. Do not put coordinates in the URL.
    • The access_token parameter must be part of the POST URL, not the body. All other parameters must be part of the request body.

    A POST request for the Map Matching API or the Directions API looks like this:

    POST /{api_name}/{api_version}/mapbox/{profile}?access_token={your_access_token} HTTP/1.0
    Content-Type: application/x-www-form-urlencoded
    
    coordinates={lon1,lat1;lon2,lat2;...;lonN,latN}
    

    Example HTTP POST requests

    # POST request to Map Matching API
    $ 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"
    
    # POST request to Directions API with optional parameters
    $ 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&waypoints=0;6&waypoint_names=Home;Work&banner_instructions=true" "https://api.mapbox.com/directions/v5/mapbox/driving?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    

    Directions

    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 for the driving, walking, and cycling profiles, or up to three coordinates for the driving-traffic profile

    This API supports 4 different routing profiles:

    ProfileDescription
    mapbox/driving-trafficFor automotive routing. This profile factors in current and historic traffic conditions to avoid slowdowns. Traffic information is available in these supported geographies. Requests using this profile accept up to three coordinates.
    mapbox/drivingFor automotive routing. This profile shows the fastest routes by preferring high-speed roads like highways. Requests using this profile accept up to 25 coordinates.
    mapbox/walkingFor pedestrian and hiking routing. This profile shows the shortest path by using sidewalks and trails. Requests using this profile accept up to 25 coordinates.
    mapbox/cyclingFor bicycle routing. This profile shows routes that are short and safer for cyclists by avoiding highways and preferring streets with bike lanes. Requests using this profile accept up to 25 coordinates.

    Retrieve directions

    get
    /directions/v5/{profile}/{coordinates}

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

    Try this in the API Playground.

    Required parametersDescription
    profileThe routing profile to use. Possible values are mapbox/driving-traffic, mapbox/driving, mapbox/walking, or mapbox/cycling.
    coordinatesA semicolon-separated list of {longitude},{latitude} coordinate pairs to visit in order. There can be between two and 25 coordinates for most requests, or up to three coordinates for driving-traffic requests.

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

    Optional parametersDescription
    alternativesWhether to try to return alternative routes (true) or not (false, default). An alternative route is a route that is significantly different than the fastest route, but also still reasonably fast. Such a route does not exist in all circumstances. Up to two alternatives may be returned.
    annotations

    (Requires overview=full)
    Return additional metadata along the route. Possible values are: duration, distance, speed, and congestion. You can include several annotations as a comma-separated list. See the route leg object for more details on what is included with annotations.
    bearings

    (Requires the radiuses parameter)
    Influences the direction in which a route starts from a waypoint. Used to filter the road segment the waypoint will be placed on by direction. This is useful for making sure the new routes of rerouted vehicles continue traveling in their current direction. A request that does this would provide bearing and radius values for the first waypoint and leave the remaining values empty. Takes two comma-separated values per waypoint: an angle clockwise from true north between 0 and 360, and the range of degrees by which the angle can deviate (recommended value is 45° or 90°), formatted as {angle, degrees}. If provided, the list of bearings must be the same length as the list of coordinates. However, you can skip a coordinate and show its position in the list with the ; separator.
    continue_straightSets the allowed direction of travel when departing intermediate waypoints. If true, the route will continue in the same direction of travel. If false, the route may continue in the opposite direction of travel. Defaults to true for mapbox/driving and false for mapbox/walking and mapbox/cycling.
    excludeExclude certain road types from routing. The default is to not exclude anything from the profile selected. The following exclude flags are available for each profile:
    ProfileAvailable excludes
    mapbox/drivingOne of toll, motorway, or ferry
    mapbox/driving-trafficOne of toll, motorway, or ferry
    mapbox/walkingNo excludes supported
    mapbox/cyclingferry
    geometriesThe format of the returned geometry. Allowed values are: geojson (as LineString), polyline (default, a polyline with a precision of five decimal places), polyline6 (a polyline with a precision of six decimal places).
    overviewThe type of returned overview geometry. Can be full (the most detailed geometry available), simplified (default, a simplified version of the full geometry), or false (no overview geometry).
    radiusesThe maximum distance a coordinate can be moved to snap to the road network in meters. There must be as many radiuses as there are coordinates in the request, each separated by ;. Values can be any number greater than 0 or the string unlimited. A NoSegment error is returned if no routable road is found within the radius.
    stepsWhether to return steps and turn-by-turn instructions (true) or not (false, default).

    If steps is set to true, the following guidance-related parameters will be available:
    approaches

    (Requires steps=true)
    A semicolon-separated list indicating the side of the road from which to approach waypoints in a requested route. Accepts unrestricted (default, route can arrive at the waypoint from either side of the road) or curb (route will arrive at the waypoint on the driving_side of the region). If provided, the number of approaches must be the same as the number of waypoints. However, you can skip a coordinate and show its position in the list with the ; separator. Since the first value will not be evaluated, begin the list with a semicolon.
    banner_instructions

    (Requiressteps=true)
    Whether to return banner objects associated with the route steps (true) or not (false, default).
    language

    (Requires steps=true)
    The language of returned turn-by-turn text instructions. See supported languages. The default is en (English).
    roundabout_exits

    (Requires steps=true)
    Whether to emit instructions at roundabout exits (true) or not (false, default). Without this parameter, roundabout maneuvers are given as a single instruction that includes both entering and exiting the roundabout. With roundabout_exits=true, this maneuver becomes two instructions, one for entering the roundabout and one for exiting it.
    voice_instructions

    (Requires steps=true)
    Whether to return SSML marked-up text for voice guidance along the route (true) or not (false, default).
    voice_units

    (Requires steps=true and voice_instructions=true)
    Specify which type of units to return in the text for voice instructions. Can be imperial (default) or metric.
    waypoint_names

    (Requires steps=true)
    A semicolon-separated list of custom names for entries in the list of coordinates, used for the arrival instruction in banners and voice instructions. Values can be any string, and the total number of all characters cannot exceed 500. If provided, the list of waypoint_names must be the same length as the list of coordinates, but you can skip a coordinate pair and show its position in the list with the ; separator. The first value in the list corresponds to the route origin, not the first destination. To leave the origin unnamed, begin the list with a semicolon.
    waypoint_targets

    (Requires steps=true)
    A semicolon-separated list of coordinate pairs used to specify drop-off locations that are distinct from the locations specified in coordinates. If this parameter is provided, the Directions API will compute the side of the street, left or right, for each target based on the waypoint_targets and the driving direction. The maneuver.modifier, banner and voice instructions will be updated with the computed side of street. The number of waypoint_targets must be the same as the number of coordinates, but you can skip a coordinate pair and show its position in the list with the ; separator. Since the first value will not be evaluated, begin the list with a semicolon.
    waypointsA semicolon-separated list indicating which input coordinates should be treated as waypoints. Waypoints form the beginning and end of each leg in the returned route, and when the steps=true parameter is used, correspond to the depart and arrive steps. If a list of waypoints is not provided, all coordinates are treated as waypoints. Each item in the list must be the zero-based index of an input coordinate, and the list must include 0 (the index of the first coordinate) and the index of the last coordinate. The waypoints parameter can be used to guide the path of the route without introducing additional legs and arrive/depart instructions.

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

    Example request: Retrieve directions

    # 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"
    
    # Specify waypoints
    
    $ curl "https://api.mapbox.com/directions/v5/mapbox/driving/13.43,52.51;13.42,52.5;13.43,52.5?waypoints=0;2&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Use HTTP POST to retrieve directions

    The Directions API also supports access using the HTTP POST method. HTTP POST should be used for large requests, since the Directions API has a size limit of approximately 8100 bytes on GET request URLs. If you receive an HTTP 413 ("Request entity too large") or HTTP 414 ("Request URL too large") error when you make a GET request, then using HTTP POST is a good option for you.

    Learn more about this process in the Using HTTP POST section.

    Response: Retrieve directions

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

    PropertyDescription
    codeA string indicating the state of the response. This is a different code than the HTTP status code. On normal valid responses, the value will be Ok. For other responses, see the Directions API errors table.
    waypointsAn array of waypoint objects. Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates.
    routesAn array of route objects ordered by descending recommendation rank. The response object may contain at most two routes.

    Example response: Retrieve directions

    {
      "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"
    }
    

    Waypoint object

    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:

    PropertyDescription
    nameA string with the name of the road or path to which the input coordinate has been snapped.
    locationAn array containing the [longitude, latitude] of the snapped coordinate.
    distance

    (optional)
    The straight-line distance from the coordinate specified in the query to the location it was snapped to.

    Example waypoint object

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

    Route object

    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:

    PropertyDescription
    durationA float indicating the estimated travel time through the waypoints in seconds.
    distanceA float indicating the distance traveled through the waypoints in meters.
    weight_nameA string indicating which weight was used. The default is routability, which is duration-based, with additional penalties for less desirable maneuvers.
    weightA float indicating the weight in units described by weight_name.
    geometryDepending on the geometries query parameter, this is either a GeoJSON LineString or a Polyline string. Depending on the overview query parameter, this is the complete route geometry (full), a simplified geometry to the zoom level at which the route can be displayed in full (simplified), or is not included (false).
    legsAn array of route leg objects.
    voiceLocaleA string of the locale used for voice instructions. Defaults to en (English). Can be any accepted instruction language. voiceLocale is only present in the response when voice_instructions=true.

    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"
    }
    

    Route leg object

    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:

    PropertyDescription
    distanceA number indicating the distance traveled between waypoints in meters.
    durationA number indicating the estimated travel time between waypoints in seconds.
    stepsDepending on the optional steps parameter, either an array of route step objects (steps=true) or an empty array (steps=false, default).
    summaryA string summarizing the route.
    annotationAn annotations object that contains additional details about each line segment along the route geometry. Each entry in an annotations field corresponds to a coordinate along the route geometry.
    annotation.distanceThe distance between each pair of coordinates in meters.
    annotation.durationThe duration between each pair of coordinates in seconds.
    annotation.speedThe average speed used in the calculation between the two points in each pair of coordinates in meters per second.
    annotation.congestionThe level of congestion, described as severe, heavy, moderate, low or unknown, between each entry in the array of coordinate pairs in the route leg. For any profile other than mapbox/driving-traffic a list of unknowns will be returned. A list of unknowns will also be returned if the route is very long.

    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": ""
    }
    

    Route step object

    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:

    PropertyDescription
    maneuverOne step maneuver object.
    distanceA number indicating the distance traveled in meters from the maneuver to the next route step.
    durationA number indicating the estimated time traveled in seconds from the maneuver to the next route step.
    geometryDepending on the geometries parameter, this is a GeoJSON LineString or a Polyline string representing the full route geometry from this route step to the next route step.
    nameA string with the name of the road or path that forms part of the route step.
    refAny road designations associated with the road or path leading from this step’s maneuver to the next step’s maneuver. If multiple road designations are associated with the road, they are separated by semicolons. Typically consists of an alphabetic network code (identifying the road type or numbering system), a space or hyphen, and a route number. Optionally included, if data is available.
    Note: A network code is not necessarily globally unique, and should not be treated as though it is. A route number may not uniquely identify a road within a given network.
    destinationsA string with the destinations of the road or path along which the travel proceeds. Optionally included, if data is available.
    exitsA string with the exit numbers or names of the road or path. Optionally included, if data is available.
    driving_sideThe legal driving side at the location for this step. Either left or right.
    modeA string indicating the mode of transportation.
    ProfilePossible values
    mapbox/driving driving, ferry, unaccessible
    mapbox/walkingwalking, ferry, unaccessible
    mapbox/cyclingcycling, walking, ferry, train, unaccessible
    pronunciationA string containing an IPA phonetic transcription indicating how to pronounce the name in the name property. Omitted if pronunciation data is not available for the step.
    intersectionsAn array of objects representing all the intersections along the step:
    intersections.locationA [longitude, latitude] pair describing the location of the turn.
    intersections.bearingsA list of bearing values that are available at the intersection. The bearings describe all available roads at the intersection.
    intersections.classesAn array of strings signifying the classes of the road exiting the intersection.
    Possible valuesDescription
    tollRoad continues on a toll road
    ferryRoad continues on a ferry
    restrictedRoad continues on with access restrictions
    motorwayRoad continues on a motorway
    tunnelRoad continues in a tunnel
    intersections.entryA list of entry flags, corresponding with the entries in bearings. If true, indicates that the respective road could be entered on a valid route. If false, the turn onto the respective road would violate a restriction.
    intersections.inThe index in the bearings and entry arrays. Used to calculate the bearing before the turn. Namely, the clockwise angle from true north to the direction of travel before the maneuver/passing the intersection. To get the bearing in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for departure maneuvers.
    intersections.outThe index in the bearings and entry arrays. Used to extract the bearing after the turn. Namely, the clockwise angle from true north to the direction of travel after the maneuver/passing the intersection. The value is not supplied for arrival maneuvers.
    intersections.lanesAn array of lane objects that represent the available turn lanes at the intersection. If no lane information is available for an intersection, the lanes property will not be present.

    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"
    }
    

    Step maneuver object

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

    PropertyDescription
    bearing_beforeA number between 0 and 360 indicating the clockwise angle from true north to the direction of travel immediately before the maneuver.
    bearing_afterA number between 0 and 360 indicating the clockwise angle from true north to the direction of travel immediately after the maneuver.
    instructionA human-readable instruction of how to execute the returned maneuver.
    locationAn array of [longitude, latitude] coordinates for the point of the maneuver.
    modifierAn optional string indicating the direction change of the maneuver. The meaning of each modifier depends on the type property.
    Possible valuesDescription
    uturnIndicates a reversal of direction. type can be turn or continue when staying on the same road.
    sharp rightA sharp right turn.
    rightA normal turn to the right.
    slight rightA slight turn to the right.
    straightNo relevant change in direction.
    slight leftA slight turn to the left.
    leftA normal turn to the left.
    sharp leftA sharp turn to the left.
    typeA string indicating the type of maneuver. See the full list of maneuver types in the maneuver types table.
    • 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

    typeDescription
    turnA basic turn in the direction of the modifier.
    new nameThe road name changes (after a mandatory turn).
    departIndicates departure from a leg. The modifier value indicates the position of the departure point in relation to the current direction of travel.
    arriveIndicates arrival to a destination of a leg. The modifier value indicates the position of the arrival point in relation to the current direction of travel.
    mergeMerge onto a street.
    on rampTake a ramp to enter a highway.
    off rampTake a ramp to exit a highway.
    forkTake the left or right side of a fork.
    end of roadRoad ends in a T intersection.
    continueContinue on a street after a turn.
    roundaboutTraverse roundabout. Has an additional property exit in the route step that contains the exit number. The modifier specifies the direction of entering the roundabout.
    rotaryA traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer rotary_name parameters, rotary_pronunciation parameters, or both, located in the route step object in addition to the exit property.
    roundabout turnA small roundabout that is treated as an intersection.
    notificationIndicates a change of driving conditions, for example changing the mode from driving to ferry.
    exit roundaboutIndicates the exit maneuver from a roundabout. Will not appear in results unless you supply the roundabout_exits=true query parameter in the request.
    exit rotaryIndicates the exit maneuver from a rotary. Will not appear in results unless you supply the roundabout_exits=true query parameter in the request.

    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"
    }
    

    Lane object

    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.

    PropertyDescription
    validIndicates whether a lane can be taken to complete the maneuver (true) or not (false). For instance, if the lane array has four objects and the first two are valid, the driver can take either of the left lanes and stay on the route.
    indicationsAn array of indications (based on signs, road markings, or both) for each turn lane. A road can have multiple indications. For example, a turn lane can have a sign with an arrow pointing left and another arrow pointing straight.
    Possible valuesDescription
    noneNo dedicated indication is shown
    straightAn indication signaling to continue straight
    sharp leftAn indication signaling a sharp left turn
    leftAn indication signaling a left turn
    slight leftAn indication signaling a slight left turn
    slight right An indication signaling a slight right turn
    rightAn indication signaling a right turn
    sharp rightAn indication signaling a sharp right turn
    uturnAn indication signaling the possibility to reverse direction by making a u-turn

    Example lane object

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

    Voice instruction object

    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 system will announce the instructions during the route step in which the voice instruction object is nested, but the instructions refer to the maneuver in the following step.

    PropertyDescription
    distanceAlongGeometryA float indicating how far from the upcoming maneuver the voice instruction should begin in meters.
    announcementA string containing the text of the verbal instruction.
    ssmlAnnouncementA string with SSML markup for proper text and pronunciation. This property is designed for use with Amazon Polly. The SSML tags may not work with other text-to-speech engines.

    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.

    PropertyDescription
    distanceAlongGeometryA float indicating how far from the upcoming maneuver the banner instruction should begin being displayed in meters. Only one banner should be displayed at a time.
    primaryThe most important content to display to the user. This text is larger and at the top.
    secondary
    (optional)
    Additional content useful for visual guidance. This text is slightly smaller and below primary. Can be null.
    sub
    (optional)
    Additional information that is included if the driver needs to be notified about something. Can include information about the next maneuver (the one after the upcoming one) if the step is short. If lane information is available, that takes precedence over information about the next maneuver.

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

    PropertyDescription
    textA string that contains all the text that should be displayed.
    type
    (optional)
    The type of maneuver. May be used in combination with the modifier (and, if it is a roundabout, the degrees) for an icon to display. Possible values: turn, merge, depart, arrive, fork, off ramp, and roundabout.
    modifier
    (optional)
    The modifier for the maneuver. Can be used in combination with the type (and, if it is a roundabout, the degrees) for an icon to display.
    Possible valuesDescription
    uturnIndicates a reversal of direction
    sharp rightA sharp right turn
    rightA normal turn to the right
    slight rightA slight turn to the right
    straightNo relevant change in direction
    slight leftA slight turn to the left
    leftA normal turn to the left
    sharp leftA sharp turn to the left
    degrees
    (optional)
    The degrees at which you will be exiting a roundabout, assuming 180 indicates going straight through the roundabout.
    driving_side
    (optional)
    A string representing which side the of the street people drive on in that location. Can be left or right.
    componentsObjects that, together, make up what should be displayed in the banner. Includes additional information intended to be used to aid in visual layout. A component can contain the following properties:
    components.typeA string with more context about the component that may help in visual markup and display choices. If the type of the component is unknown, it should be treated as text.
    Possible valuesDescription
    textDefault. Indicates the text is part of the instructions and no other type.
    icon This is text that can be replaced by an imageBaseURL icon.
    delimiterThis is text that can be dropped, and should be dropped if you are rendering icons.
    exit-numberIndicates the exit number for the maneuver.
    exitProvides the the word for exit in the local language.
    laneIndicates which lanes can be used to complete the maneuver.
    The introduction of new types is not considered a breaking change.
    components.textThe sub-string of the text of the parent objects that may have additional context associated with it
    components.abbr
    (optional)
    The abbreviated form of text. If this is present, there will also be an abbr_priority value. For an example of using abbr and abbr_priority, see the abbreviation examples table.
    components.abbr_priority
    (optional)
    An integer indicating the order in which the abbreviation abbr should be used in place of text. The highest priority is 0, while a higher integer value means it should have a lower priority. There are no gaps in integer values. Multiple components can have the same abbr_priority. When this happens, all components with the same abbr_priority should be abbreviated at the same time. Finding no larger values of abbr_priority means that the string is fully abbreviated.
    components.imageBaseURL
    (optional)
    A string pointing to a shield image to use instead of the text.
    components.directions
    (optional)
    An array indicating which directions you can go from a lane (left, right, or straight). If the value is ['left', 'straight'], the driver can go straight or left from that lane. Present if components.type is lane.
    components.active
    (optional)
    A boolean that tells you whether that lane can be used to complete the upcoming maneuver. If multiple lanes are active, then they can all be used to complete the upcoming maneuver. Present if components.type is lane.

    Abbreviation examples

    textabbrabbr_priority
    NorthN1
    Franklin DriveFranklin Dr0

    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
              }
            ]
        }
    }
    

    Instructions languages

    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.

    CodeLanguage
    arArabic
    daDanish
    deGerman
    enEnglish
    eoEsperanto
    esSpanish
    es-ESSpanish (Spain)
    fiFinnish
    frFrench
    heHebrew
    huHungarian
    idIndonesian
    itItalian
    koKorean
    jaJapanese
    myBurmese
    nlDutch
    noNorwegian (Bokmål)
    plPolish
    pt-BRPortuguese (Brazil)
    pt-PTPortuguese (Portugal)
    roRomanian
    ruRussian
    slSlovene
    svSwedish
    trTurkish
    ukUkrainian
    viVietnamese
    zh-HansChinese (Simplified)

    Directions API errors

    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.

    Response body codeHTTP status codeDescription
    Ok200Normal success case.
    NoRoute200There was no route found for the given coordinates. Check for impossible routes (for example, routes over oceans without ferry connections).
    NoSegment200No road segment could be matched for coordinates. Check for coordinates that are too far away from a road.
    ProfileNotFound404Use a valid profile as described in the list of routing profiles.
    InvalidInput422The given request was not valid. The message key of the response will hold an explanation of the invalid input.

    Directions API restrictions and limits

    • 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.

    Isochrone

    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.

    Retrieve isochrones around a location

    get
    /isochrone/v1/{profile}/{coordinates}?{contours_minutes}

    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.

    Required parametersDescription
    profileA Mapbox Directions routing profile ID. Options are mapbox/driving for travel times by car, mapbox/walking for pedestrian and hiking travel times, and mapbox/cycling for travel times by bicycle.
    coordinatesA {longitude,latitude} coordinate pair around which to center the isochrone lines.
    contours_minutesThe times in minutes to use for each isochrone contour. You can specify up to four contours. Times must be in increasing order. The maximum time that can be specified is 60 minutes.

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

    Optional parametersDescription
    contours_colorsThe colors to use for each isochrone contour, specified as hex values without a leading # (for example, ff0000 for red). If this parameter is used, there must be the same number of colors as there are entries in contours_minutes. If no colors are specified, the Isochrone API will assign a default rainbow color scheme to the output.
    polygonsSpecify whether to return the contours as GeoJSON polygons (true) or linestrings (false, default). When polygons=true, any contour that forms a ring is returned as a polygon.
    denoiseA floating point value from 0.0 to 1.0 that can be used to remove smaller contours. The default is 1.0. A value of 1.0 will only return the largest contour for a given time value. A value of 0.5 drops any contours that are less than half the area of the largest contour in the set of contours for that same time value.
    generalizeA positive floating point value in meters used as the tolerance for Douglas-Peucker generalization. There is no upper bound. If no value is specified in the request, the Isochrone API will choose the most optimized generalization to use for the request. Note that the generalization of contours can lead to self-intersections, as well as intersections of adjacent contours.

    Example request: Retrieve isochrones around a location

    $ 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"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Retrieve isochrones around a location

    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:

    PropertyDescription
    typeFeature, a GeoJSON type from the GeoJSON specification.
    propertiesAn object that describes how the isochrone should be drawn.
    properties.contourThe time in minutes used for the isochrone contour.
    properties.colorThe color of the isochrone line if the geometry property is Linestring.
    properties.opacityThe opacity of the isochrone line if the geometry property is Linestring.
    properties.fillThe fill color of the isochrone polygon if the geometry property is Polygon, suitable for use in geojson.io.
    properties.fill-opacityThe fill opacity of the isochrone polygon if the geometry property is Polygon, suitable for use in geojson.io.
    properties.fillColorThe fill color of the isochrone polygon if the geometry property is Polygon, suitable for use in Leaflet.
    properties.fillOpacityThe fill opacity of the isochrone polygon if the geometry property is Polygon, suitable for use in Leaflet.
    geometryAn object that describes the geometry of the isochrone.
    geometry.coordinatesAn array of arrays that contain the coordinates for the isochrone, formatted as [longitude,latitude].
    geometry.typeThe GeoJSON type of the returned geometry. Either Linestring (default) or Polygon (if polygons=true was specified in the query).

    Example response: Retrieve isochrones around a location

    {
        "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"
    }
    

    Isochrone API restrictions and limits

    • The Isochrone API is limited to 300 requests per minute.
    • The Isochrone API supports 1 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.

    Map Matching

    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.

    Turn-by-turn directions in the Map Matching API

    The Map Matching API can also return a full directions response to queries using the optional steps parameter. If you plan use the Map Matching API to return turn-by-turn directions, note that it does not consider all road rules and traffic conditions. To access up-to-date traffic and road conditions for navigation purposes, use the Mapbox Directions API.

    Retrieve a match

    get
    /matching/v5/{profile}/{coordinates}.json

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

    Required parametersDescription
    profileA Mapbox Directions routing profile ID.
    Profile IDDescription
    mapbox/drivingCar travel times, distances, or both.
    mapbox/walkingPedestrian and hiking travel times, distances, or both
    mapbox/cyclingBicycle travel times, distances, or both
    mapbox/driving-trafficCar travel times, distances, or both as informed by traffic data
    coordinatesA semicolon-separated list of {longitude},{latitude} coordinate pairs to visit in order. There can be between 2 and 100 coordinates.

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

    Optional parametersDescription
    annotationsReturn additional metadata along the route. Possible values are: duration, distance, and speed. You can include several annotations as a comma-separated list. See the route leg object for more details on what is included with annotations.
    approachesA semicolon-separated list indicating the side of the road from which to approach waypoints in a requested route. Accepts unrestricted (default, route can arrive at the waypoint from either side of the road) or curb (route will arrive at the waypoint on the driving_side of the region). If provided, the number of approaches must be the same as the number of waypoints. However, you can skip a coordinate and show its position in the list with the ; separator. If waypoints is not specified (so all coordinates are treated as waypoints), the list of approaches must be the same length as the list of coordinates. Must be used in combination with steps=true.
    geometriesThe format of the returned geometry. Allowed values are: geojson (as LineString), polyline (default, a polyline with precision 5), and polyline6 (a polyline with precision 6).
    languageThe language of returned turn-by-turn text instructions. See supported languages. The default is en (English). Must be used in combination with steps=true.
    overviewThe type of returned overview geometry. Can be full (the most detailed geometry available), simplified (default, a simplified version of the full geometry), or false (no overview geometry).
    radiusesA semicolon-separated list indicating the maximum distance a coordinate can be moved to snap to the road network in meters. If provided, the number of radiuses must be the same as the number of coordinates. However, you can skip a coordinate and show its position in the list with the ; separator. Values can be a number between 0.0 and 50.00. Use higher numbers (20-50) for noisy traces and lower numbers (1-10) for clean traces. The default value is 5.
    stepsWhether to return steps and turn-by-turn instructions (true) or not (false, default).
    tidyWhether to remove clusters and re-samples traces for improved map matching results (true) or not (false, default).
    timestampsA semicolon-separated list of numbers in Unix time (in other words, seconds since 1/1/1970 UTC) that correspond to each input coordinate. If provided, the number of timestamps must be the same as the number of coordinates, no coordinates can be skipped, and the timestamps must occur in ascending order. For best results, timestamps should have a sample rate of about 5 seconds.
    waypoint_namesA semicolon-separated list of custom names for waypoints. These names will be used for the arrival instruction in banners and voice instructions. Values can be any string, and the total number of all characters (including semicolons) cannot exceed 500. The list of waypoint_names must be the same length as the list of waypoints, but you can skip a waypoint and show its position with the ; separator. If waypoints is not specified (so all coordinates are treated as waypoints), the list of waypoint_names must be the same length as the list of coordinates.
    waypointsA semicolon-separated list indicating which input coordinates should be treated as waypoints. If a coordinate is treated as a waypoint, it receives arrival and departure events in the match object's route. If a list of waypoints is not provided, all coordinates are treated as waypoints. Each item in the list must be the zero-based index of an input coordinate, and the list must include 0 (the index of the first coordinate) and the index of the last coordinate. Waypoints are most useful in combination with steps=true and requests based on traces with high sample rates.

    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: Retrieve a match

    # 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 one 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"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Use HTTP POST to retrieve a match

    The Map Matching API also supports access using the HTTP POST method. HTTP POST should be used for large requests, since the Map Matching API has a size limit of approximately 8100 bytes on GET request URLs. If you receive an HTTP 413 ("Request entity too large") or HTTP 414 ("Request URL too large") error when you make a GET request, then using HTTP POST is a good option for you.

    Learn more about this process in the Using HTTP POST section.

    Response: Retrieve a match

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

    PropertyDescription
    codeA string indicating the state of the response. The potential values are listed in the Map Matching status codes section.
    matchingsAn array of match objects.
    tracepointsAn array of tracepoint objects that represent the location an input point was matched with, in the order in which they were matched. If a trace point is omitted by the Map Matching API because it is an outlier, the entry will be null.

    With clean matches, only one match object is returned. When 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 response: Retrieve a match
    {
      "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"
    }
    

    Match object

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

    PropertyDescription
    confidenceA float indicating the level of confidence in the returned match, from 0 (low) to 1 (high).
    distanceA float indicating the distance traveled in meters.
    durationA float indicating the estimated travel time in seconds.
    weightA string indicating the weight in the units described by weight_name.
    weight_nameA string indicating the weight that was used. The default is routability, which is duration-based with additional penalties for less desirable maneuvers.
    geometryDepending on the geometries parameter in the request, this is a GeoJSON LineString or a Polyline string. Depending on the overview parameter in the request, this is the complete route geometry (full), a simplified geometry to the zoom level at which the route can be displayed in full (simplified), or is not included (false).
    legsAn array of route leg objects.
    voice_localeThe locale used for voice instructions. Defaults to en (English). See supported languages. Optionally included if steps=true.
    Example match object
    {
        "confidence": 0.9548844020537051,
        "distance": 103.7,
        "duration": 16.4,
        "geometry": "gatfEfidjUi@Le@@Y?E??J?^Hf@",
        "legs": []
    }
    

    Tracepoint object

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

    PropertyDescription
    matchings_indexThe index of the match object in matchings that the sub-trace was matched to.
    waypoint_indexThe index of the waypoint inside the matched route.
    alternatives_countThe number of probable alternative matchings for this trace point. A value of 0 indicates that this point was matched unambiguously. Split the trace at these points for incremental map matching.
    nameThe name of the road or path the coordinate snapped to.
    locationAn array that contains the location of the snapped coordinate, in the format [longitude, latitude].
    Example tracepoint object
    {
        "waypoint_index": 0,
        "location": [-117.172836, 32.71204],
        "name": "North Harbor Drive",
        "matchings_index": 0,
        "alternatives_count": 0
    }
    

    Map Matching API errors

    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.
    Status codeDescription
    OkNormal case
    NoMatchThe input did not produce any matches, or the waypoints requested were not found in the resulting match. features will be an empty array.
    TooManyCoordinatesThere are more than 100 points in the request.
    InvalidInputmessage will hold an explanation of the invalid input.
    ProfileNotFoundNeeds to be a valid profile (mapbox/driving, mapbox/driving-traffic, mapbox/walking, or mapbox/cycling).

    Map Matching API restrictions and limits

    • 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.

    Matrix

    The Mapbox Matrix API returns travel times between many points.

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

    ABC
    AA → AA → BA → C
    BB → AB → BB → C
    CC → AC → BC → C

    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.

    Retrieve a matrix

    get
    /directions-matrix/v1/{profile}/{coordinates}

    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.

    Required parametersDescription
    profileA Mapbox Directions routing profile ID.
    Profile IDDescription
    mapbox/drivingCar travel times, distances, or both.
    mapbox/walkingPedestrian and hiking travel times, distances, or both
    mapbox/cyclingBicycle travel times, distances, or both
    mapbox/driving-trafficCar travel times, distances, or both as informed by traffic data
    coordinatesA semicolon-separated list of {longitude},{latitude} coordinates. There must be between two and 25 coordinates.

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

    Optional parametersDescription
    annotationsUsed to specify the resulting matrices. Possible values are: duration (default), distance, or both values separated by a comma.
    approachesA semicolon-separated list indicating the side of the road from which to approach waypoints in a requested route. Accepts unrestricted (default, route can arrive at the waypoint from either side of the road) or curb (route will arrive at the waypoint on the driving_side of the region). If provided, the number of approaches must be the same as the number of waypoints. However, you can skip a coordinate and show its position in the list with the ; separator.
    destinationsUse the coordinates at a given index as destinations. Possible values are: a semicolon-separated list of 0-based indices, or all (default). The option all allows using all coordinates as destinations.
    fallback_speedBy default, if there is no possible route between two points, the Matrix API sets the resulting matrix element to null. To circumvent this behavior, set the fallback_speed parameter to a value greater than 0 in kilometers per hour. The Matrix API will replace a null value with a straight-line estimate between the source and destination based on the provided speed value.
    sourcesUse the coordinates at a given index as sources. Possible values are: a semicolon-separated list of 0-based indices, or all (default). The option all allows using all coordinates as sources.

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

    Example request: Retrieve a matrix

    # 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"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Retrieve a matrix

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

    PropertyDescription
    codeA string indicating the state of the response. This is a separate code than the HTTP status code. On normal valid responses, the value will be Ok. See the errors section below for more information.
    durationsDurations as an array of arrays that represent the matrix in row-major order. durations[i][j] gives the travel time from the ith source to the jth destination. All values are in seconds. The duration between the same coordinate is always 0. If a duration cannot be found, the result is null.
    distancesDistances as an array of arrays that represent the matrix in row-major order. distances[i][j] gives the travel distance from the ith source to the jth destination. All values are in meters. The distance between the same coordinate is always 0. If a distance cannot be found, the result is null.
    sourcesAn array of waypoint objects. Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates, or in the order specified in the sources query parameter.
    destinationsAn array of waypoint objects. Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates, or in the order specified in the destinations query parameter.

    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: Retrieve a matrix

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

    Matrix API errors

    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.

    Response body codeHTTP status codeDescription
    Ok200Normal success case.
    ProfileNotFound404Use a valid profile as described in Retrieve a matrix.
    InvalidInput422The given request was not valid. The message key of the response will hold an explanation of the invalid input.

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

    Matrix API restrictions and limits

    • 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.

    Optimization

    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.

    Retrieve an optimization

    get
    /optimized-trips/v1/{profile}/{coordinates}

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

    Required parametersDescription
    profileA Mapbox Directions routing profile ID.
    Profile IDDescription
    mapbox/drivingCar travel times, distances, or both.
    mapbox/walkingPedestrian and hiking travel times, distances, or both
    mapbox/cyclingBicycle travel times, distances, or both
    The Optimization API does not support the mapbox/driving-traffic profile.
    coordinatesA semicolon-separated list of {longitude},{latitude} coordinates. There must be between two and 12 coordinates. The first coordinate is the start and end point of the trip.

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

    Optional parametersDescription
    annotationsReturn additional metadata along the route. You can include several annotations as a comma-separated list. Possible values are:
    annotationsDescription
    durationThe duration between each pair of coordinates in seconds
    distanceThe distance between each pair of coordinates in meters
    speedThe speed between each pair of coordinates in meters per second
    approachesA semicolon-separated list indicating the side of the road from which to approach waypoints in a requested route. Accepts unrestricted (default, route can arrive at the waypoint from either side of the road) or curb (route will arrive at the waypoint on the driving_side of the region). If provided, the number of approaches must be the same as the number of waypoints. However, you can skip a coordinate and show its position in the list with the ; separator. Must be used in combination with steps=true.
    bearingsInfluences the direction in which a route starts from a waypoint. Used to filter the road segment on which a waypoint will be placed by direction. This is useful for making sure the new routes of rerouted vehicles continue traveling in their current direction. A request that does this would provide bearing and radius values for the first waypoint and leave the remaining values empty. Must be used in conjunction with the radiuses parameter. Takes 2 values per waypoint: an angle clockwise from true north between 0 and 360, and the range of degrees by which the angle can deviate (recommended value is 45° or 90°), formatted as {angle, degrees}. If provided, the list of bearings must be the same length as the list of waypoints. However, you can skip a coordinate and show its position in the list with the ; separator.
    destination
    (optional)
    Specify the destination coordinate of the returned route. Accepts any (default) or last.
    distributionsSpecify pick-up and drop-off locations for a trip by providing a ; delimited list of number pairs that correspond with the coordinates list. The first number of a pair indicates the index to the coordinate of the pick-up location in the coordinates list, and the second number indicates the index to the coordinate of the drop-off location in the coordinates list. Each pair must contain exactly 2 numbers, which cannot be the same. The returned solution will visit pick-up locations before visiting drop-off locations. The first location can only be a pick-up location, not a drop-off location.
    geometriesThe format of the returned geometry. Allowed values are: geojson (as LineString), polyline (default, a polyline with precision 5), polyline6 (a polyline with precision 6).
    languageThe language of returned turn-by-turn text instructions. See supported languages. The default is en (English).
    overviewThe type of the returned overview geometry. Can be full (the most detailed geometry available), simplified (default, a simplified version of the full geometry), or false (no overview geometry).
    radiusesThe maximum distance a coordinate can be moved to snap to the road network in meters. There must be as many radiuses as there are coordinates in the request, each separated by ;. Values can be any number greater than 0 or the string unlimited. A NoSegment error is returned if no routable road is found within the radius.
    sourceThe coordinate at which to start the returned route. Accepts any (default) or first.
    stepsWhether to return steps and turn-by-turn instructions (true) or not (false, default).
    roundtripIndicates whether the returned route is roundtrip, meaning the route returns to the first location (true, default) or not (false). If roundtrip=false, the source and destination parameters are required but not all combinations will be possible. See the Fixing Start and End Points section below for additional notes.

    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:

    roundtripsourcedestinationsupported
    truefirstlastyes
    truefirstanyyes
    trueanylastyes
    trueanyanyyes
    falsefirstlastyes
    falsefirstanyno
    falseanylastno
    falseanyanyno

    Example request: Retrieve an optimization

    # 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"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Retrieve an optimization

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

    PropertyDescription
    codeA string indicating the state of the response. This is a separate code than the HTTP status code. On normal valid responses, the value will be Ok.
    waypointsAn array of waypoint objects. Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates.
    tripsAn array of 0 or 1 trip objects.
    Waypoint objects

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

    PropertyDescription
    nameA string with the name of the road or path that the input coordinate snapped to.
    locationAn array containing the [longitude, latitude] of the snapped coordinate.
    trips_indexThe index of the trip object that contains this waypoint in the trips array.
    waypoint_indexThe index of the position of the given waypoint within the trip.
    Trip object

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

    PropertyDescription
    geometryDepending on the geometries parameter, this is either a GeoJSON LineString or a Polyline string. Depending on the overview parameter, this is the complete route geometry (full), a simplified geometry to the zoom level at which the route can be displayed in full (simplified), or is not included (false).
    legsAn array of route leg objects.
    weight_nameA string indicating which weight was used. The default is routability, which is duration-based, with additional penalties for less desirable maneuvers.
    weightA float indicating the weight in the units described by weight_name.
    durationA float indicating the estimated travel time in seconds.
    distanceA float indicating the distance traveled in meters.

    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}[12 coordinates per request
    - Maximum 25 distributions per request
    - Maximum 300 requests per minute
    
    For higher volumes, [contact us](https://www.mapbox.com/contact/).