Directions

Directions API version

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 for the supported geographies listed in our Traffic Data page. 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.
playground
Directions API playground

Retrieve directions between waypoints and see the results on a map.

Retrieve directions

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

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

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. This is available for mapbox/driving-traffic, mapbox/driving, or mapbox/cycling.
annotationsReturn additional metadata along the route. You can include several annotations as a comma-separated list. Must be used in conjunction with overview=full.
Possible valuesDescription
distanceThe distance between each pair of coordinates in meters.
durationThe duration between each pair of coordinates in seconds.
speedThe speed between each pair of coordinates in meters per second.
congestionThe level of congestion between each entry in the array of coordinate pairs in the route leg. This annotation is only available for the mapbox/driving-traffic profile.
congestion_numericThe numeric level of congestion between each entry in the array of coordinate pairs in the route leg. This annotation is only available for the mapbox/driving-traffic profile.
maxspeed
Beta
The maximum speed limit between the coordinates of a segment. This annotation is only available for the mapbox/driving and mapbox/driving-traffic profiles.
closureAn array of closure objects describing live-traffic related closures that occur along the route. This annotation is only available for the mapbox/driving-traffic profile.
See the route leg object for more details on what is included with annotations.
bearingsInfluences 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 or more of toll, motorway, or ferry
mapbox/driving-trafficOne or more 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).
overviewDisplays the requested type of 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.
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. Since the first value will not be evaluated, begin the list with a semicolon. If the waypoint is within 1 meter of the road, this parameter is ignored.
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:
banner_instructionsWhether to return banner objects associated with the route steps (true) or not (false, default). Must be used in conjunction with steps=true.
languageThe language of returned turn-by-turn text instructions. See supported languages. The default is en (English). Must be used in conjunction with steps=true.
roundabout_exitsWhether 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. Must be used in conjunction with steps=true.
voice_instructionsWhether to return SSML marked-up text for voice guidance along the route (true) or not (false, default). Must be used in conjunction with steps=true.
voice_unitsSpecify which type of units to return in the text for voice instructions. Can be imperial (default) or metric. Must be used in conjunction with be used in conjunction with steps=true and voice_instructions=true.
waypoint_namesA 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. Must be used in conjunction with steps=true.
waypoint_targetsA 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. Must be used in conjunction with steps=true.
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. Must be used in conjunction with steps=true.
alley_biasA scale from -1 to 1, where -1 biases the route against alleys and 1 biases the route toward alleys. The default is 0, which is neutral.

Optional parameters for the mapbox/walking profile

Optional v5/mapbox/walking parametersDescription
walking_speedThe walking speed in meters per second with a minimum of 0.14 m/s (or 0.5 km/h) and a maximum of 6.94 m/s (or 25.0 km/h). Defaults to 1.42 m/s (5.1 km/h).
walkway_biasA scale from -1 to 1, where -1 biases the route against walkways and 1 biases the route toward walkways. The default is 0, which is neutral.

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

Optional parameters for the mapbox/driving profile

Optional v5/mapbox/driving parametersDescription
arrive_byThe desired arrival time, formatted as a timestamp in ISO-8601 format in the local time at the route destination. The travel time returned in duration is a prediction for travel time based on historical travel data. The route is calculated in a time-dependent manner. For example, a trip that takes two hours will consider changing historic traffic conditions across the two-hour window. The route takes timed turn restrictions and conditional access restrictions into account based on the requested arrival time.
depart_atThe departure time, formatted as a timestamp in ISO-8601 format in the local time at the route origin. The travel time returned in duration is a prediction for travel time based on historical travel data. The route is calculated in a time-dependent manner. For example, a trip that takes two hours will consider changing historic traffic conditions across the two-hour window, instead of only at the specified depart_at time. The route takes timed turn restrictions and conditional access restrictions into account based on the requested departure time.

Optional parameters for the mapbox/driving-traffic profile

Optional v5/mapbox/driving-traffic parametersDescription
snapping_include_closuresA semicolon-separated list of booleans affecting snapping of waypoint locations to road segments. If true, road segments closed due to live-traffic closures will be considered for snapping. If false, they will not be considered for snapping. If provided, the number of snapping_include_closures 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 unspecified, this paramter defaults to false.

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 to access speed limit information using the maxspeed annotation
$ curl "https://api.mapbox.com/directions/v5/mapbox/driving/-122.39636,37.79129;-122.39732,37.79283;-122.39606,37.79349?annotations=maxspeed&overview=full&geometries=geojson&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"

# Specify a departure time

https://api.mapbox.com/directions/v5/mapbox/driving/-122.396112,37.791399;-122.433904,37.757812?access_token=YOUR_MAPBOX_ACCESS_TOKEN&depart_at=2019-05-02T15:00

Supported libraries: Retrieve directions

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. POST requests are still subject to your account's request size limits.

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.
adminsAn array of objects describing the administrative boundaries the route leg travels through. Use admin_index on the intersection object to look up the administrative boundaries for each intersection in this array.
incidentsAn array of incident objects describing temporary events that occur along the roadway. This is only provided if incidents exist and you are using the mapbox/driving-traffic profile.
admins.iso_3166_1Contains the two-letter ISO 3166-1 alpha-2 code that applies to a country boundary. Example: "US".
admins.iso_3166_1_alpha3Contains the three-letter ISO 3166-1 alpha-3 code that applies to a country boundary. Example: "USA".
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.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.
annotation.congestion_numericThe level of congestion in numeric form, from 0-100. A value of 0 indicates no congestion, a value of 100 indicates maximum congestion. Entries may be null if congestion on that segment is not known.
annotation.distanceThe distance between each pair of coordinates in meters.
annotation.durationThe duration between each pair of coordinates in seconds.
annotation.maxspeed
Beta
The local posted speed limit between each pair of coordinates. A maxspeed object contains the following properties:
PropertyDescription
speedThe maximum speed limit between the coordinates of a segment. The value can be either the legal speed limit or an advisory speed limit where posted, or none if the speed limit is unlimited (for instance, a German Autobahn).
unitThe unit of measurement that speed is expressed in, either km/h or mph. Returned in combination with speed.
unknownReturns true if the speed limit is not known.
Note that unknown will not be present if speed and unit are present in an individual maxspeed object, and that speed and unit will not be present if unknown is present.
annotation.speedThe average speed used in the calculation between the two points in each pair of coordinates in meters per second.
annotation.closureIncluded in the route leg object when making a mapbox/driving-traffic request with annotations=closure,... and there are live-traffic closures along the route. A closure object contains the following properties:
PropertyDescription
geometry_index_startThe position in the coordinate list where the closure began.
geometry_index_endThe position in the coordinate list where the closure ended.

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"
        ],
        "maxspeed": [
          {
            "speed": 56,
            "unit": "km/h"
          },
          {
            "speed": 56,
            "unit": "km/h"
          },
          {
            "speed": 56,
            "unit": "km/h"
          },
          {
            "speed": 56,
            "unit": "km/h"
          },
          {
            "speed": 56,
            "unit": "km/h"
          },
          {
            "speed": 56,
            "unit": "km/h"
          },
          {
            "speed": 56,
            "unit": "km/h"
          },
          {
            "speed": 56,
            "unit": "km/h"
          }
        ]
    },
    "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.geometry_indexThe zero-based index into the geometry for the intersection. This value can be used to apply the duration annotation that corresponds with the intersection. Only available on the driving profile.
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.
intersections.durationA number indicating the time required, in seconds, to traverse the intersection. Only available on the driving profile.
intersections.tunnel_nameThe name of the tunnel when the road exiting the intersection continues in a tunnel. This property is only included when the tunnel has a specified name. Only available on the driving profile.
intersections.mapbox_streets_v8An object containing detailed information about the road exiting the intersection along the route. Properties in this object correspond to properties in the Mapbox Streets v8 road specification. Only available on the driving profile.
intersections.mapbox_streets_v8.classThe road class of the road exiting the intersection as defined by the Mapbox Streets v8 road class specification. Valid values include, but are not limited to, those supported by Mapbox Streets v8. For example: motorway, motorway_link, primary, and street.
intersections.is_urbanA boolean indicating whether the road exiting the intersection is considered to be in an urban area. This value is determined by the density of the surrounding road network. Only available on the driving profile.
intersections.admin_indexThe zero-based index into the administrative boundaries list on the route leg for this intersection. Use this field to look up the ISO 3166-1 country code for this point on the route. Only available on the driving profile.
intersections.rest_stopAn object containing information about passing rest stops along the route. Only available on the driving profile.
intersections.rest_stop.typeThe type of rest stop, always included in the rest_stop object. Valid values include, but are not limited to, rest_area (includes parking only) and service_area (includes amenities such as gas or restaurants).
intersections.toll_collectionAn object containing information about a toll collection point along the route. This is a payment booth or overhead electronic gantry where a toll charge may be collected. Only available on the driving profile.
intersections.toll_collection.typeThe type of toll collection point, always included in the toll_collection object. Valid values include, but are not limited to, toll_booth and toll_gantry.
speedLimitSignThe basic design of speed limit signs along the route step, either mutcd (Manual on Uniform Traffic Control Devices) or vienna (Vienna Convention on Road Signs and Signals). Only present in the response when the annotations query parameter contains maxspeed.
speedLimitUnitThe unit of measurement for speed that is used locally along the step, either km/h or mph. This unit is an appropriate default unit to display in the absence of a user preference; it may differ from the unit property of the annotation objects. Only present in the response when the annotations query parameter contains maxspeed.

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,
            "active": true,
            "valid_indication": "straight",
            "indications": [ "left", "straight" ]
          },
          {
            "valid": true,
            "active": false,
            "valid_indication": "straight",
            "indications": [ "straight", "right" ]
          },
          {
            "valid": false,
            "active": 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.
activeIndicates whether this lane is a preferred lane (true) or not (false). A preferred lane is a lane that is recommended if there are multiple lanes available. For example, if guidance indicates that the driver must turn left at an intersection and there are multiple left turn lanes, the left turn lane that will better prepare the driver for the next maneuver will be marked as active. Only available on the mapbox/driving profile.
valid_indicationWhen either valid or active is set to true, this property shows which of the lane indications is applicable to the current route, when there is more than one. For example, if a lane allows you to go left or straight but your current route is guiding you to the left, then this value will be set to left. See indications for possible values. When both active and valid are false, this property will not be included in the response. Only available on the mapbox/driving profile.
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,
    "active": true,
    "valid_indication": "left",
    "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. The shield image can be retrieved as an SVG by appending .svg to the URL string, or it can be retrieved as a PNG at 1-3× pixel density by appending `@1x
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.
components.active_direction
(optional)
When components.active is set to true, this property shows which of the lane's components.directions is applicable to the current route, when there is more than one. For example, if a lane allows you to go left or straight but your current route is guiding you to the left, then this value will be set to left. See component.directions for possible values. When components.active is false, this property will not be included in the response. Only available on the mapbox/driving profile.

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

Incident object

The incident object is included in the route leg object when making a mapbox/driving-traffic request in cases where there are incidents along the route.

PropertyDescription
idThe unique ID of the incident.
typeThe type of incident this is. It can be one of several possible incidents including: accident, congestion, construction, disabled_vehicle, lane_restriction, mass_transit, miscellaneous, other_news, planned_event, road_closure, road_hazard, weather.
descriptionA short description of the incident in a human-readable format.
long_descriptionA long description of the incident in a human-readable format.
creation_timeA string representing when this incident first appeared as an incident on the map in ISO-8601 format (for example, 2020-12-18T15:56:53Z).
start_timeA string representing when this incident was started or is expected to start in ISO-8601 format (for example, 2020-12-18T15:56:53Z).
end_timeA string representing when this incident ended or is expected to end in ISO-8601 format (for example, 2020-12-18T15:56:53Z).
impactA string representing the impact of the incident on local traffic. Can be one of: unknown, critical, major, minor, low.
alertc_codesAn array of integers that give more detailed information about the type of incident. For the full list of alert codes, see the OpenStreetMap wiki's event code list.
lanes_blockedAn array of lanes that are blocked by the incident. Some examples of values include: left, left center, left turn lane, center, right, right center, right turn lane, hov.
num_lanes_blockedThe number of items in the lanes_blocked array.
congestionAn object containing information about the amount of congestion on the road around the incident.
congestion.valueA number between 0 and 101 representing the level of congestion caused by the incident. The higher the number, the more congestion there is. A value of 0 means there is no congestion on the road. A value of 100 means that the road is closed. A value of 101 means that no congestion was calculated.
closedIf this is true then the road has been completely closed.
geometry_index_startThe position in the coordinate list where the incident began.
geometry_index_endThe position in the coordinate list where the incident ended.
sub_typeThis could contain additional information about the type of incident.
sub_type_descriptionThis could contain detail about the value of the sub_type field.

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
yoYoruba
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 one or more coordinates within the supplied radiuses. 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.
  • Requests that contain multiple coordinates are counted as 1 request.
  • Maximum total of 10,000 kilometers between all waypoints.
If you require a higher rate limit, contact us.

Directions API pricing

  • Billed by requests
  • See rates and discounts per Directions API request in the pricing page's Navigation section

Usage of the Directions API is measured in API requests. A request that contains multiple waypoints is billed as a single API request. Details about the number of Directions API requests included in the free tier and the cost per request beyond what is included in the free tier are available on the pricing page.