Directions API

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, driving-traffic, walking, and cycling profiles
• Calculate routes for electric vehicles to reach destinations with optimal charging stops as well as battery prediction

Routing profiles

The Directions API supports 4 different routing profiles:

Retrieve directions

Required parameters

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

Optional parameters

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

Optional parameters for the mapbox/walking profile

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

Optional parameters for the mapbox/driving profile

Optional parameters for the mapbox/driving-traffic profile

Example requests: 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"

# Assign layers to waypoints, to handle ambiguities in the case of multi-level roads

$ curl "https://api.mapbox.com/directions/v5/mapbox/driving/13.43,52.51;13.42,52.5;13.43,52.5?layers=-1;;3&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

$ curl "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:

• Mapbox Directions for Swift
• Mapbox Java SDK
• Mapbox JavaScript SDK
• Mapbox Ruby SDK

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

Response: Retrieve directions

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

Example response: Retrieve directions

NEW waypoints_per_route=true

{
  "routes": [
    {
      "geometry": "mnn_Ick}pAfBiF`CzA",
      "waypoints": [ // A waypoint array specific to this route
        { // A regular, user-submitted waypoint (the origin).
          "name": "Köpenicker Straße",
          "location": [ 13.426579, 52.508068 ]
        },
        { // A regular, user-submitted waypoint (the destination).
          "name": "Engeldamm",
          "location": [ 13.427292, 52.506902 ]
        }
      ],
      "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,
                  "sub": 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": "auto",
      "weight": 44.4,
      "duration": 26.2,
      "distance": 176.7
    },
    {  // A second route object or alternative route with potentially another set of waypoints
      "geometry": "mnn_Ick}pAfBiF`CzA",
      "waypoints": [ // A waypoint array specific to this route
        { // A regular, user-submitted waypoint (the origin).
          "name": "alt1_origin",
          "location": [ 13.426579, 52.508068 ]
        },
        { // A regular, user-submitted waypoint (the destination).
          "name": "alt1_destination",
          "location": [ 13.427292, 52.506902 ]
        }
      ],
      "legs": [
        { ... }
      ],
      "weight_name": "auto",
      "weight": 44.4,
      "duration": 26.2,
      "distance": 176.7
    }
  ],
  "code": "Ok",
  "uuid": "cjd51uqn5005447p8nte2zc4w"
}

OLD waypoints_per_route=false / default

{
  "routes": [
    {
      ...
    }
  ],
  "waypoints": [
    {
      "name": "Köpenicker Straße",
      "location": [ 13.426579, 52.508068 ]
    },
    {
      "name": "Engeldamm",
      "location": [ 13.427292, 52.506902 ]
    }
  ],
  "code": "Ok",
  "uuid": "cjd51uqn5005447p8nte2zc4w"
}

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.

Electric Vehicle Routing

EV routing automatically identifies if charging is needed and if so, adds charging stops along the journey with optimal charge time and charging level for each stop. The charging stops are returned as waypoints with additional metadata in the route response. In some cases such as when range is too low to reach nearby charging stations, EV route may contain no charging stops with state of charge annotations going below 0%. Customize the EV route by defining the battery characteristics, vehicle dynamics and user preferences. See Parameters for Electric Vehicle Routing.

Parameters for Electric Vehicle Routing

EV routing is available in driving and driving-traffic profiles. Request an EV route by setting the parameter engine=electric; the other parameters apply only when that is set. EV routing requests can specify up to 10 total waypoints. If ev_add_charging_stops is false, EV routing requests can specify up to 25 total waypoints

Charging station data

The Mapbox EV Routing processes charging stations from Europe and North America and builds a digital graph of interconnected stations. When you make an EV route request, the router will pick up the nearest stations along the route and identify the fastest chargers that are compatible with the driver’s model of EV.

Supported geographies for EV Routing

Mapbox EV Router supports the following geographies for EV trip planning:

Example EV route request

$ curl "https://api.mapbox.com/directions/v5/mapbox/driving/11.59838875578771,48.1498484882143;11.646071564986642,48.157168731123306.json?overview=false&alternatives=true&waypoints_per_route=true&engine=electric&ev_initial_charge=600&ev_max_charge=50000&ev_connector_types=ccs_combo_type1,ccs_combo_type2&energy_consumption_curve=0,300;20,160;80,140;120,180&ev_charging_curve=0,100000;40000,70000;60000,30000;80000,10000&ev_min_charge_at_charging_station=1&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Example EV Alternative route response with EV charging stops

NEW waypoints_per_route=true, alternatives=true

{
  "routes": [
    {
      "weight_name": "auto",
      "weight": 729.764,
      "duration": 1371.657958984375,
      "distance": 4575.367,
      "waypoints": [  // A waypoint array specific to this route
        { // A regular, user-submitted waypoint (the origin).
          "name": "Ifflandstraße",
          "location": [
            11.59804,
            48.149988
          ],
          "distance": 30.207000732421875,
          "metadata": null
        },
        { // A silent waypoint, i.e. does not create a new leg.
          // It only describes where it matched to the route.
          "metadata": {
            "type": "silent",
            "distance_from_route_start": 2088,
            "geometry_index": 11
          },
          ...
        },
        { // A charging-station waypoint inserted by the routing engine during
          // an EV route request
          "name": "Arabellastraße",
          "location": [
            11.617788,
            48.153125
          ],
          "distance": 18.554000854492188,
          "metadata": {
            "type": "charging-station",
            "name": "BayWa Zentrale",
            "charge_time": 788,
            "charge_to": 5369,
            "charge_at_arrival": 250,
            "plug_type": "ccs_combo_type2",
            "power_kw": 150,
            "station_id": "ocm-128831",
            "provider_names": ["Tesla", "Shell Recharge Solutions"],
          }
        },
        { // A regular, user-submitted waypoint (the destination).
          "name": "Barlowstraße",
          "location": [
            11.646591,
            48.156744
          ],
          "distance": 1.1330000162124634,
          "metadata": null
        }
      ],
      "legs": [
        {
          "via_waypoints": [],
          "summary": "Ifflandstraße, B 2R",
          "admins": [
            {
              "iso_3166_1_alpha3": "DEU",
              "iso_3166_1": "DE"
            }
          ],
          "weight": 333.797,
          "duration": 255.738,
          "steps": [],
          "distance": 2262.614
        },
        {
          "via_waypoints": [],
          "summary": "Arabellastraße, Englschalkinger Straße",
          "admins": [
            {
              "iso_3166_1_alpha3": "DEU",
              "iso_3166_1": "DE"
            }
          ],
          "weight": 395.967,
          "duration": 327.92,
          "steps": [],
          "distance": 2312.754
        }
      ]
    },
    {  // A second Route object, our alternative route with potentially another set of waypoints
      "geometry": "mnn_Ick}pAfBiF`CzA",
      "waypoints": [ // A waypoint array specific to this route
        { // A regular, user-submitted waypoint (the origin).
          "metadata": {
            "type": "regular"
          },
          "name": "alt1_origin",
          "distance": 1.1330000162124634
        },
        { // A charging-station waypoint inserted by the routing engine during an EV route request
          "metadata": {
            "type": "charging-station",
            "name": "charge1",
            ...
          },
          ...
        },
        { // A regular, user-submitted waypoint (the destination).
          "name": "alt1_destination",
          "location": [
            11.646591,
            48.156744
          ],
          "distance": 1.1330000162124634,
          "metadata": {
            "type": "regular"
          }
        }
        ],
          "legs": [
            { ... }
          ],
          "weight_name": "auto",
          "weight": 44.4,
          "duration": 26.2,
          "distance": 176.7
        }
  ],
  "code": "Ok",
  "uuid": "QJuXPALlclx4ciVHn-UPxhqlUD0W7jjiv1tXFH_haUpp_VkdD0sqGQ=="
}

OLD waypoints_per_route=false / default, no alternatives

{
  "routes": [
    {
      "weight_name": "auto",
      "weight": 729.764,
      "duration": 1371.657958984375,
      "distance": 4575.367,
      "legs": [
        {
          "via_waypoints": [],
          "summary": "Ifflandstraße, B 2R",
          "admins": [
            {
              "iso_3166_1_alpha3": "DEU",
              "iso_3166_1": "DE"
            }
          ],
          "weight": 333.797,
          "duration": 255.738,
          "steps": [],
          "distance": 2262.614
        },
        {
          "via_waypoints": [],
          "summary": "Arabellastraße, Englschalkinger Straße",
          "admins": [
            {
              "iso_3166_1_alpha3": "DEU",
              "iso_3166_1": "DE"
            }
          ],
          "weight": 395.967,
          "duration": 327.92,
          "steps": [],
          "distance": 2312.754
        }
      ]
    }
  ],
  "waypoints": [
    {
      "name": "Ifflandstraße",
      "location": [
        11.59804,
        48.149988
      ],
      "distance": 30.207000732421875,
      "metadata": null
    },
    {
      "name": "Arabellastraße",
      "location": [
        11.617788,
        48.153125
      ],
      "distance": 18.554000854492188,
      "metadata": {
        "type": "charging-station",
        "name": "BayWa Zentrale",
        "charge_time": 788,
        "charge_to": 5369,
        "charge_at_arrival": 250,
        "plug_type": "ccs_combo_type2",
        "power_kw": 150,
        "station_id": "ocm-128831",
        "provider_names": ["Tesla", "Shell Recharge Solutions"],
      }
    },
    {
      "name": "Barlowstraße",
      "location": [
        11.646591,
        48.156744
      ],
      "distance": 1.1330000162124634,
      "metadata": null
    }
  ],
  "code": "Ok",
  "uuid": "QJuXPALlclx4ciVHn-UPxhqlUD0W7jjiv1tXFH_haUpp_VkdD0sqGQ=="
}

Charging waypoint metadata

The Directions API returns charging stops as waypoints along the route. Each charging waypoint has additional metadata describing the charging stop. The following attributes are present in the metadata object:

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:

Example waypoint object

{
    "name": "Kirkjubøarvegur",
    "location": [ -6.80897, 62.000075 ],
    "distance": 25,
    "metadata": { // metadata only for EV-routing
      "type": "charging-station",
      "name": "BayWa Zentrale",
      "charge_time": 788,
      "charge_to": 5369,
      "charge_at_arrival": 250,
      "plug_type": "ccs_combo_type2",
      "power_kw": 150,
      "station_id": "ocm-128831",
      "provider_names": ["Tesla", "Shell Recharge Solutions"]
    }

}

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:

Example route object

{
    "waypoints": [], // only with waypoints_per_route=true
    "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

Route leg objects are nested within the route object. A route leg is the journey from an origin point to a destination point, so a route will usually contain one fewer route legs than it has number of input coordinates. Using the waypoints= parameter will override this. For example:

• A route request with two input coordinates defines one leg with no waypoints.
• A route request with three input coordinates defines two legs with one waypoint.
• A route request with four input coordinates will have two legs if it includes the waypoints= parameter specifying three waypoints.

Each route leg object contains the following properties:

Example route leg object

{
    "via_waypoints": [
        {
          "waypoint_index": 1,
          "distance_from_start": 127.951,
          "geometry_index": 6
        },
        {
          "waypoint_index": 2,
          "distance_from_start": 236.822,
          "geometry_index": 10
        }
    ],
    "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": 99.824,
    "weight": 131.349,
    "distance": 580.039,
    "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:

Example route step object

{
    "intersections": [
      {
        "out": 1,
        "location": [ 13.424671, 52.508812 ],
        "bearings": [ 120, 210, 300 ],
        "entry": [ false, true, true ],
        "in": 0,
        "stop_sign": true,
        "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:

Maneuver types

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.

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.

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

Banner instruction object

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

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

Abbreviation examples

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

• North Franklin Dr
• N Franklin Dr

Example banner instruction object

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

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.

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.

Simplified Chinese, Welsh, and Icelandic are supported in private preview, contact us for more information.

Use of the underscore as a language code separator is supported too, like nl_NL. The language parameter is case-insensitive.

Notification object

The notifications.details object is specific to the notification type and subtype.

Available violations (notifications.type=violation)

violation is more severe in nature and are delivered when user-set parameters (ex: exclude=unpaved) are violated during route generation.

{
  "type": "violation",
  "subtype": "maxHeight",
  "geometry_index_end": 5,
  "geometry_index_start": 3,
  "details": {
    "actual_value": "4.60",
    "requested_value": "4.70",
    "unit": "meters",
    "message": "The height of the vehicle (4.7 meters) is more than the permissible height of travel on the road (4.6 meters) by 0.10 meters."
  }
}

{
  "type": "violation",
  "subtype": "maxWidth",
  "geometry_index_end": 2,
  "geometry_index_start": 1,
  "details": {
    "actual_value": "4.69",
    "requested_value": "5.10",
    "unit": "meters",
    "message": "The width of the vehicle (5.1 meters) is more than the permissible width of travel on the road (4.69 meters) by 0.41 meters."
  }
}

{
  "type": "violation",
  "subtype": "maxWeight",
  "geometry_index_end": 1,
  "geometry_index_start": 0,
  "details": {
    "actual_value": "4.60",
    "requested_value": "5.10",
    "unit": "metric tons",
    "message": "The weight of the vehicle (5.1 metric tons) is more than the permissible weight of travel on the road (4.6 metric tons) by 0.50 metric tons."
  }
}

{
  "type": "violation",
  "subtype": "unpaved",
  "geometry_index_end": 3,
  "geometry_index_start": 2,
  "details": {
    "requested_value": "paved",
    "actual_value": "dirt",
    "message": "The road has an unpaved surface (dirt)."
  }
}

{
  "type": "violation",
  "subtype": "pointExclusion",
  "geometry_index_end": 3,
  "geometry_index_start": 2,
  "details": {
    "message": "The road was marked as undesirable for routing due to the exclusion by point[1.004941,0.996407]."
  }
}

{
  "type": "violation", 
  "subtype": "countryBorderCrossing",
  "geometry_index_end": 1,
  "geometry_index_start": 0,
  "details": {
    "actual_value": "US,CA",
    "message": "Crossing the border of the countries of US and CA."
  }
}

{
  "type": "violation",
  "subtype": "stateBorderCrossing",
  "geometry_index_end": 1,
  "geometry_index_start": 0,
  "details": {
    "actual_value": "US-NV,US-CA",
    "message": "Crossing the border of the states of US-NV and US-CA."
  }
}

Available alerts (notifications.type=alert)

alert is less severe in nature and are meant to inform users when implicit preferences are unable to be met (ex: countryBorderCrossing).

{
  "type": "alert",
  "subtype": "countryBorderCrossing",
  "geometry_index_end": 1,
  "geometry_index_start": 0,
  "details": {
    "actual_value": "US,CA",
    "message": "Crossing the border of the countries of US and CA."
  }
}

{
  "type": "alert",
  "subtype": "stateBorderCrossing",
  "geometry_index_end": 1,
  "geometry_index_start": 0,
  "details": {
    "actual_value": "US-NV,US-CA",
    "message": "Crossing the border of the states of NV and CA."
  }
}

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.

Directions API restrictions and limits

• Requests using the driving, driving-traffic, walking, and cycling profiles can specify up to 25 total waypoints (input coordinates that are snapped to the roads network) along the route. However, if using engine=electric, you can specify up to a total of 10 waypoints.
  • 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 distance between all waypoints:
  • 10,000 kilometers for the driving and driving-traffic profiles.
  • 10,000 kilometers for the cycling profile.
  • 1,000 kilometers for the walking profile.
• Inter-continental route requests are not supported.
• Route requests through water bodies are not supported.

Directions API pricing

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.