Skip to main content

Directions API

Directions API version

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

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:

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 25 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 optimal 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
https://api.mapbox.com/directions/v5/{profile}/{coordinates}

Required parameters

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

Required parametersTypeDescription
profilestringThe routing profile to use. Possible values are mapbox/driving-traffic, mapbox/driving, mapbox/walking, or mapbox/cycling.
coordinatesnumberA semicolon-separated list of between two and 25 {longitude},{latitude} coordinate pairs to visit in order.

Optional parameters

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

Optional parametersTypeDescription
alternativesbooleanWhether to try to return alternative routes (true) or not (false, default). An alternative route is a route that is significantly different from the fastest route, but still close in time. 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, mapbox/cycling and mapbox/walking.
annotationsstringReturn 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 available only 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.
state_of_charge
BETA
The battery's current state of charge as a percentage of the maximum capacity. The value can be negative, signifying a charge deficit. Positive values show the battery's charge level.
See the route leg object for more details on what is included with annotations.
avoid_maneuver_radiusnumberAdd a radius around the starting point in which the API will avoid returning any significant maneuvers. Possible values are in the range from 1 to 1000 meters. Use this option when the vehicle is traveling at a significant speed to avoid dangerous maneuvers when re-routing. If a route is not found using the specified value, it will be ignored. Note that if a large radius is used, the API may ignore an important turn and return a long straight path before the first maneuver. The avoid_maneuver_radius parameter cannot be used with the arrive_by=<time> or depart_at=<time> options, since these modes are used for reference requests, not for real-time routing. But you can use the depart_at=now option. This is available for mapbox/driving-traffic and mapbox/driving.
bearingsintegerInfluences 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. But, you can skip a coordinate and show its position in the list with the ; separator.
layersintegerInfluences the layer of road from which a route starts from a waypoint. Used to filter the road segment the waypoint will be placed on, in Z-order. This is useful to avoid ambiguity in the case of multi-level roads (for example, a tunnel under a road). Takes a single signed integer per waypoint. If provided, the list of layers must be the same length as the list of coordinates. But, you can skip a coordinate and show its position in the list with the ; separator. Corresponds to the layer field in Mapbox Streets v8. Note that if a matching layer is not found, the API will choose a suitable layer according to other provided parameters.
continue_straightbooleanSets 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.
excludestringExclude certain road types and custom locations from routing. Default is to not exclude anything from the list below. You can specify multiple values as a comma-separated list. The following exclude values are available:
Possible valuesDescription
motorwayExclude highways or motorways. Available in mapbox/driving and mapbox/driving-traffic profiles.
tollExclude roads with tolls. Available in mapbox/driving and mapbox/driving-traffic profiles.
ferryExclude ferry rides across waterways. Available in mapbox/driving, mapbox/driving-traffic, mapbox/cycling and mapbox/walking profiles.
unpavedExclude dirt roads or track. Available in mapbox/driving and mapbox/driving-traffic profiles.
cash_only_tollsExclude roads with tolls that accept only cash. Available in mapbox/driving, mapbox/driving-traffic, mapbox/walking and mapbox/cycling profiles.
point(longitude latitude)
BETA
Exclude custom locations such as dangerous entry/exit points, bridges, tunnels, low quality roads and cross border roads. Coordinate specified in WKT format will be snapped to the nearest road and the snapped coordinate will be excluded from routing. You can specify multiple coordinates with a comma-separated list. For example point(lon1 lat1), point(lon2 lat2). Note that at most 50 points are allowed per API request. Available in mapbox/driving and mapbox/driving-traffic profiles.
country_border
BETA
Exclude crossing of any controlled country border. Note that borders within the Schengen Area will not be excluded. Available in mapbox/driving and mapbox/driving-traffic profiles.
state_border
BETA
Exclude crossing of any state border. Available in mapbox/driving and mapbox/driving-traffic profiles.
geometriesstringThe 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).
includestringInclude certain additional road types for routing. The default is to not include these road types. You can specify multiple values as a comma-separated list. The following include values are available:
Possible valuesDescription
hov2A road type that requires a minimum of two vehicle occupants. Available in mapbox/driving and mapbox/driving-traffic profiles.
hov3A road type that requires a minimum of three vehicle occupants. Available in mapbox/driving and mapbox/driving-traffic profiles.
hotA high occupancy toll road that is tolled if your vehicle doesn't meet the minimum occupant requirement. Available in mapbox/driving and mapbox/driving-traffic profiles.
overviewstringDisplays 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).
radiusesnumber or stringThe 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 located within the radius.
approachesstringA 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. But, 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.
stepsbooleanWhether to return steps and turn-by-turn instructions (true) or not (false, default).

Setting steps to true will make the following guidance-related parameters available: banner_instructions, language, roundabout_exits, voice_instructions, voice_units, waypoint_names, waypoint_targets, and waypoints.
banner_instructionsbooleanWhether to return banner objects associated with the route steps (true) or not (false, default). Must be used in conjunction with steps=true.
languagestringThe 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_exitsbooleanWhether to emit instructions at roundabout exits (true) or not (false, default). Without this parameter, roundabout maneuvers are returned 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_instructionsbooleanWhether 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_unitsstringSpecify which type of units to return in the text for voice instructions. Can be imperial (default) or metric. Must be used in conjunction with steps=true and voice_instructions=true.
waypointsintegerA 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.
waypoints_per_routebooleanIf true, the waypoints array is returned within the route object, else its returned at the root of the response body. Defaults to false if unspecified. Available in mapbox/driving, mapbox/driving-traffic and mapbox/walking profiles.
Setting waypoints_per_route to true is necessary when asking for an EV-optimized route with alternatives, since each alternative route may produce separate sets of waypoints (charging stations).
waypoint_namesstringA 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 waypoints, but you can skip a waypoint coordinate 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_targetsnumberA 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 waypoints, but you can skip a waypoint 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. Must be used in conjunction with steps=true.
notifications
BETA
stringReturns notification metadata associated with the route leg of the route object. Notifications allow the exposure of warnings or safety messages within your application, or important insights about your route. Available in mapbox/driving and mapbox/driving-traffic profiles.
Possible valuesDescription
allInclude all notification metadata.
noneDo not provide notifications in route metadata.
The default is all. See the notification object for more details on what is included with notifications.

Optional parameters for the mapbox/walking profile

Optional v5/mapbox/walking parametersTypeDescription
walking_speednumberThe 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_biasnumberA 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 parametersTypeDescription
alley_biasnumberA 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.
arrive_bystringThe desired arrival time, formatted in one of three ISO 8601 formats: YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm. In the last format, the timezone is calculated from 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_atstringThe departure time, formatted in one of three ISO 8601 formats: YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm. In the last format, the timezone is calculated from 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.
max_heightnumberThe max vehicle height, in meters. If this parameter is provided, the Directions API will compute a route that includes only roads with a height limit greater than or equal to the max vehicle height. max_height must be between 0 and 10 meters. The default value is 1.6 meters. Coverage for road height restriction may vary by region.
max_widthnumberThe max vehicle width, in meters. If this parameter is provided, the Directions API will compute a route that includes only roads with a width limit greater than or equal to the max vehicle width. max_width must be between 0 and 10 meters. The default value is 1.9 meters. Coverage for road width restriction may vary by region.
max_weightnumberThe max vehicle weight, in metric tons (1000 kg). If this parameter is provided, the Directions API will compute a route that includes only roads with a weight limit greater than or equal to the max vehicle weight. max_weight must be between 0 and 100 metric tons. The default value is 2.5 metric tons. Coverage for road weight restriction may vary by region.

Optional parameters for the mapbox/driving-traffic profile

Optional v5/mapbox/driving-traffic parametersTypeDescription
depart_atstringThe departure time, formatted in one of three ISO 8601 formats: YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm. In the last format, the timezone is calculated from the route origin. The travel time, returned in duration, is a prediction for travel time based on historical travel data and live traffic. Live traffic is gently mixed with historical data when the value for depart_at is close to current time. The route takes timed turn restrictions and conditional access restrictions into account based on the requested arrival time.
snapping_include_closuresbooleanA semicolon-separated list of boolean values affecting snapping of coordinate 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 coordinates. But, you can skip a coordinate and show its position in the list with the ; separator. If unspecified, this parameter defaults to false.
snapping_include_static_closuresbooleanA semicolon-separated list of boolean values affecting snapping of coordinate locations to road segments. If true, road segments statically closed, that is long-term, will be considered for snapping (for example, road under construction). If false, they will not be considered for snapping. If provided, the number of snapping_include_static_closures must be the same as the number of coordinates. But, you can skip a coordinate and show its position in the list with the ; separator. If unspecified, this parameter defaults to false.
max_heightnumberThe max vehicle height, in meters. If this parameter is provided, the Directions API will compute a route that includes only roads with a height limit greater than or equal to the max vehicle height. max_height must be between 0 and 10 meters. The default value is 1.6 meters. Coverage for road height restriction may vary by region.
max_widthnumberThe max vehicle width, in meters. If this parameter is provided, the Directions API will compute a route that includes only roads with a width limit greater than or equal to the max vehicle width. max_width must be between 0 and 10 meters. The default value is 1.9 meters. Coverage for road width restriction may vary by region.
max_weightnumberThe max vehicle weight, in metric tons (1000 kg). If this parameter is provided, the Directions API will compute a route that includes only roads with a weight limit greater than or equal to the max vehicle weight. max_weight must be between 0 and 100 metric tons. The default value is 2.5 metric tons. Coverage for road weight restriction may vary by region.

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:

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:

PropertyTypeDescription
codestringA code 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.
waypoints
LEGACY
arrayAn 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.
📌 Deprecation Notice
The location of the waypoints property at the root of the response is now deprecated. You can continue to use this and it will work as-is. It remains the default structure (waypoints_per_route=false). We have added a waypoints_per_route=true parameter to request the new waypoints response moving forward. This is necessary when asking for an EV-optimized route with alternatives. See the new waypoints_per_route parameter in the optional parameters and the new waypoints per route object waypoints in the route object.
routesarrayAn array of route objects ordered by descending recommendation rank. The response object may contain at most two routes.
uuidstringA unique identifier, you can use to reference the response for successfully built route(s). Combination of uuid and the index in routes array uniquely identifies the route.

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

Electric Vehicle Routing Private Preview

The Directions API now supports electric vehicle (EV) routing that includes EV trip planning and battery prediction along the route, making smarter EVs that are easier to use. For pricing and to sign up for the EV Routing Private Preview, contact EV Sales

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 the former is true. EV routing requests can specify up to 12 total waypoints. If ev_add_charging_stops is false, EV routing requests can specify up to 25 total waypoints

ParametersTypeDescription
enginestringSet to electric to enable electric vehicle routing. If this parameter is not specified, routing will default to non-electric vehicles.
ev_initial_chargeintegerOptional parameter to specify initial charge of vehicle in Wh (watt-hours) at the beginning of the route. Example value of 10000 denotes initial battery of 10 kWh. The default value is equal to ev_max_charge.
ev_max_chargeintegerRequired parameter that defines the maximum possible charge of vehicle in Wh (watt-hours). Example value of 80000 denotes a battery capacity of 80 kWh.
ev_connector_typesstringRequired parameter that defines the compatible connector-types for the vehicle. The router will select the charging stations compatible with connector-types. Following connector-types are supported:
Possible valuesDescription
ccs_combo_type1Combined Charging System J-plug with fast charging DC
ccs_combo_type2Combined Charging System Mennekes with fast charging DC
teslaProprietary connector for tesla vehicles
chademoCHAdeMO fast-charging system
energy_consumption_curvestringRequired parameter that specifies in pairs the energy consumption in watt-hours per kilometer at a certain speed in kph. Example value of 0,300;20,160;80,140;120,180 defines for instance 160 watt-hours per kilometer at 20 km/h.
ev_charging_curvestringRequired parameter that specifies the maximum battery charging rate (W) at a given charge level (Wh) in a list of pairs. Example value of 0,100000; 40000,70000; 60000,30000; 80000,10000 defines for instance 70 kW charging when the battery has 40 kWh charge. The charging curve's charging levels should span from 0 to maximum charge. The first element's charging rate is assumed to be constant between the 0 and the first element's charging level. The last element's charging rate is assumed to be constant between the last element's charging level and ev_max_charge.
ev_unconditioned_charging_curvestringOptional parameter that specifies the maximum battery charging rate (W) at a specified charge level (Wh) in a list of pairs when the battery is in an unconditioned state (for example, cold). This is used in conjunction with the ev_pre_conditioning_time parameter, as a result both must be supplied when using either optional field. If only one of these parameters is supplied, this is considered an invalid query and will be rejected. An unconditioned battery may affect the charge time, and may impact the ETA as a result. By accounting for an unconditioned battery with ev_unconditioned_charging_curve and ev_pre_conditioning_time a more exact ETA can be calculated. Example value of 0,50000; 42000,35000; 60000,15000; 80000,5000 defines for instance 35 kW charging when the battery has 42 kWh charge. If the battery conditioning parameters are not provided, the standard ev_charging_curve is used for calculating charge times. The unconditioned charging curve's charging levels should span from 0 to maximum charge. The first element's charging rate is assumed to be constant between the 0 and the first element's charging level. The last element's charging rate is assumed to be constant between the last element's charging level and ev_max_charge.
ev_pre_conditioning_timeintegerOptional parameter that defines the time in minutes it would take for the vehicle's battery to condition. This is used in conjunction with the ev_unconditioned_charging_curve parameter, as a result both must be supplied when using either optional field. If only one of these parameters is supplied, this is considered an invalid query and will be rejected. An unconditioned battery may affect the charge time, and may impact the ETA as a result. By accounting for an unconditioned battery with ev_unconditioned_charging_curve and ev_pre_conditioning_time a more exact ETA can be calculated. Example value of 10 denotes it will take 10 minutes for the battery to reach a conditioned state. If the next EV charging stop occurs within 10 minutes of the estimated drive, the ev_unconditioned_battery_charging_curve is used to estimate charging times at the EV stop. If an EV charging stop occurs after ev_pre_conditioning_time of driving time has elapsed, it is assumed the battery is conditioned and the standard ev_charging_curve is used to estimate charging times. The minimum ev_pre_conditioning_time value is 0 minutes, the maximum value is 240 minutes. If the battery conditioning parameters are not provided, the standard ev_charging_curve is used for calculating charge times.
ev_max_ac_charging_powerintegerOptional parameter to specify maximum AC charging power(W) that can be delivered by the onboard vehicle charger. This parameter along with the ev_charging_curve dictates the battery charging rate. For example, when charging at a 16kW AC power outlet, with a vehicle onboard AC converter of 10kW (ev_max_ac_charging_power), router will use max charging power of 10kW. The default value is 14400W.
ev_min_charge_at_destinationintegerOptional parameter to define the minimum battery charge required at the final route destination (Wh). Example value of 20000 denotes that vehicle will reach destination with at least 20 kWh charge. ev_min_charge_at_destination must be between 0 and ev_max_charge. The default value is 10% of ev_max_charge.
ev_min_charge_at_charging_stationintegerOptional parameter to define the minimum charge when arriving at the charging station (Wh). Example value of 20000 denotes that the vehicle will reach each charging stop with at least 20 kWh charge. ev_min_charge_at_charging_station must be between 0 and ev_max_charge. The default value is 10% of ev_max_charge.
auxiliary_consumptionintegerOptional parameter to define the measure of the continuous power draw of the auxiliary systems (e.g heating, radio, air conditioning) in watts. Auxiliary consumption will affect the estimated power consumed during the trip, and may affect routing as a result. Example value of 300 denotes the vehicle's auxiliary systems are drawing 300 watts of power. The minimum value is 0 watts, the maximum value is 10000 watts.
ev_add_charging_stopsbooleanOptional parameter to specify whether EV route should add charging stops or not. When set to false, EV route will not add charging stops even if vehicle does not have enough range to complete the trip. This is useful for manually planned EV trips with user or client selecting appropriate charging stops. When set to true (default), EV route will add charging stops along the trip with optimal charge time and charging level for each stop, if needed to complete the trip with enough range.

Charging station data

The Mapbox EV Routing processes charging stations 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:

  • Australia
  • Austria
  • Belgium
  • Bulgaria
  • Canada
  • Croatia
  • Czech Republic
  • Denmark
  • Estonia
  • Finland
  • France
  • Germany
  • Greece
  • Hong Kong
  • Hungary
  • Iceland
  • Ireland
  • Israel
  • Italy
  • Japan
  • Jersey
  • Latvia
  • Liechtenstein
  • Lithuania
  • Luxembourg
  • Macao
  • Malaysia
  • Monaco
  • Netherlands
  • New Zealand
  • Norway
  • Poland
  • Portugal
  • Romania
  • Serbia
  • Singapore
  • Slovakia
  • Slovenia
  • South Africa
  • South Korea
  • Spain
  • Sweden
  • Switzerland
  • Taiwan
  • Thailand
  • Turkey
  • United Arab Emirates
  • United Kingdom
  • United States

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, as in it 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:

PropertyTypeDescription
typestringThe type of waypoint. Set to charging-station for charging stops.
namestringThe name of the EV charging station.
charge_timenumberTime in seconds the EV needs to charge for at the station.
charge_tonumberWatt-hours the EV needs to charge to at the station.
charge_at_arrivalnumberBattery charge, in Watt-hours, available on arrival at the station.
plug_typestringThe connector type to use for charging at the station. The current non-exhaustive list of possible values are:
  • ccs_combo_type1
  • ccs_combo_type2
  • chademo
  • tesla
  • mennekes_type2
  • current_typestringThe current type of the connector used for charging at the station. The current non-exhaustive list of possible values are:
  • dc
  • single_phase_ac
  • three_phase_ac
  • power_kwnumberThe maximum power available for the connector type to use for charging at the station.
    station_idstringUnique ID of the charging station.
    provider_namesarrayOptional. The charge point providers of the EV charging station. There are no guarantees provider name strings are stable.

    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:

    PropertyTypeDescription
    namestringThe name of the road or path to which the input coordinate has been snapped.
    locationarrayThe snapped coordinate as [longitude, latitude].
    time_zone
    BETA
    objectAn object describing time zone relevant information. This is only available for driving-traffic, driving and walking profiles. If using walking or driving profile, then depart_at or arrive_by must be used to receive time zone data.
    distancenumberOptional. The straight-line distance from the coordinate specified in the query to the location it was snapped to.
    metadataobjectOptional. An object describing charging stops inserted by EV Routing for routes requiring charging along the way. Its set to null for user provided waypoints including start & end locations.

    Example waypoint object

    {
    "name": "Kirkjubøarvegur",
    "location": [-6.80897, 62.000075],
    "distance": 25,
    "time_zone": {
    "abbreviation": "WET",
    "identifier": "Atlantic/Faroe",
    "offset": "+00:00"
    },
    "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"]
    }
    }

    Time Zone Information

    Each waypoint contains a time_zone object with the following fields:

    PropertyTypeDescription
    identifierstringA unique string that specifies a time zone in the format of Region/Location, for example America/New_York or Europe/Paris, as defined by the IANA Time Zone Database.
    offsetstringThe difference in hours and minutes between a specific time zone and Coordinated Universal Time (UTC), for example -05:00 for Eastern Standard Time or +01:00 for Central European Time.
    abbreviationstringOptional. A short, commonly recognized abbreviation for a time zone, often used for display purposes, for example EST for Eastern Standard Time or CET for Central European Time. Note that this field may not always be available.

    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:

    PropertyTypeDescription
    durationnumberThe estimated travel time through the waypoints, in seconds.
    distancenumberThe distance traveled through the waypoints, in meters.
    weight_namestringSpecifies the weight used, which by default is duration-based and includes additional penalties for less desirable maneuvers. For mapbox/driving & mapbox/driving-traffic its set to auto, while for mapbox/walking its set to pedestrian.
    weightnumberA numeric value representing desirability of a route, where a lower weight indicates a more favorable route when comparing two routes with the same set of waypoints. In case multiple routes are returned, they are sorted in ascending order based on their weights.
    duration_typicalnumberWhen using the driving-traffic profile, this will be returned as a float indicating the duration of the route under typical conditions (not taking into account live traffic).
    weight_typicalnumberWhen using the driving-traffic profile, this will be returned as a float indicating the weight of the selected route under typical conditions (not taking into account live traffic).
    geometrystringDepending 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).
    legsarrayAn array of route leg objects.
    voiceLocalestringThe 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.
    waypointsarrayWhen the input parameter waypoints_per_route=true is used, the waypoints will appear in the route object and display an array of waypoint objects specific to that route. Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the order traversed by the route. These waypoints can now contain additional waypoints like charging-stations, if used in EV-routing.

    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:

    PropertyTypeDescription
    distancenumberThe distance traveled between waypoints, in meters.
    durationnumberThe estimated travel time between waypoints, in seconds.
    weightnumberThe weight in units described by weight_name.
    duration_typicalnumberWhen using the driving-traffic profile, this will be returned as sign of duration of the leg under typical conditions (not taking into account live traffic).
    weight_typicalnumberWhen using the driving-traffic profile, this will be returned as sign of the weight of the leg under typical conditions (not taking into account live traffic).
    stepsarrayDepending on the optional steps parameter, either an array of route step objects (steps=true) or an empty array (steps=false, default).
    summarystringA summary of the route.
    adminsarrayAn 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.
    incidentsarrayAn 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.
    closuresarrayIncluded in the route leg object when making a mapbox/driving-traffic request with annotations=closure,... and there are live-traffic closures along the route. This is an array of closure objects which contain the following properties:
    PropertyDescription
    geometry_index_startThe position in the coordinate list where the closure began, relative to the start of the leg it's on.
    geometry_index_endThe position in the coordinate list where the closure ended, relative to the start of the leg it's on.
    admins.iso_3166_1stringContains the two-letter ISO 3166-1 alpha-2 code that applies to a country boundary. Example: "US".
    admins.iso_3166_1_alpha3stringContains the three-letter ISO 3166-1 alpha-3 code that applies to a country boundary. Example: "USA".
    annotationobjectAn 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.congestionstringThe 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.
    annotation.congestion_numericnumber or nullThe 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.distancenumberThe distance between each pair of coordinates, in meters.
    annotation.durationnumberThe duration between each pair of coordinates, in seconds.
    annotation.maxspeedobjectThe local posted speed limit between each pair of coordinates. A maxspeed object contains the following properties:
    PropertyDescription
    speed (optional)The 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
    unit (optional)The unit of measurement that speed is expressed in, either km/h or mph. Returned in combination with speed.
    unknown (optional)Returns true if the speed limit is not known.
    none (optional)Set to true if the speed limit is unlimited (for instance, a German Autobahn).
    Note that none or 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.state_of_chargenumberThe battery's current state of charge as a percentage of the maximum capacity. The value can be negative, signifying a charge deficit. Positive values show the battery's charge level. The range of values extends from negative −231 to 100, with 100 representing a fully charged battery. The state-of-charge can become negative if there are no valid routes with charging-stops. In that case, a route without additional injected charging stops will be returned, where the state-of-charge will reach and fall below 0. It is up to the client application to take appropriate measures (if any) when this happens.
    annotation.speednumberThe average speed used in the calculation between the two points in each pair of coordinates, in meters per second.
    via_waypointsarrayWhen the semicolon-separated list waypoints parameter is used in the request, an array per leg is returned that describes where a particular waypoint from the root-level array matches to the route. This provides a way for tracking when a waypoint is passed along the route. Also see the optional waypoints parameter description.
    via_waypoints.waypoint_indexnumberThe associated waypoint index, excluding the origin (index 0) and destination.
    via_waypoints.distance_from_startdoubleThe calculated distance, in meters, from the leg origin.
    via_waypoints.geometry_indexnumberThe associated leg shape index of the via waypoint location.
    notifications
    BETA
    arrayAn optional array of notification objects describing notifications about the route.

    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:

    PropertyTypeDescription
    maneuverobjectOne step maneuver object.
    distancenumberThe distance traveled, in meters, from the maneuver to the next route step.
    durationnumberThe estimated time traveled, in seconds, from the maneuver to the next route step.
    weightnumberThe weight in units described by weight_name.
    duration_typicalnumberWhen using the driving-traffic profile, this will be returned as sign of duration of the step under typical conditions (not taking into account live traffic).
    weight_typicalnumberWhen using the driving-traffic profile, this will be returned as sign of the weight of the step under typical conditions (not taking into account live traffic).
    geometrystringDepending 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.
    namestringThe name of the road or path that forms part of the route step.
    refstringAny 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.
    destinationsstringThe destinations of the road or path along which the travel proceeds. Optionally included, if data is available.
    exitsstringThe exit numbers or names of the road or path. Optionally included, if data is available.
    driving_sidestringThe legal driving side at the location for this step. Either left or right.
    modestringThe mode of transportation.
    ProfilePossible values
    mapbox/driving driving, ferry, unaccessible
    mapbox/walkingwalking, ferry, unaccessible
    mapbox/cyclingcycling, walking, ferry, train, unaccessible
    pronunciationstringAn IPA phonetic transcription indicating how to pronounce the name in the name property. Omitted if pronunciation data is not available for the step.
    intersectionsarrayAn array of objects representing all the intersections along the step:
    intersections.locationarrayA [longitude, latitude] pair describing the location of the turn.
    intersections.bearingsarrayA list of bearing values that are available at the intersection. The bearings describe all available roads at the intersection.
    intersections.classesarrayAn 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.entryarrayA list of entry flags, corresponding with the entries in bearings. If the flag is 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_indexintegerThe zero-based index into the geometry, relative to the start of the leg it's on. This value can be used to apply the duration annotation that corresponds with the intersection. Only available on the driving, driving-traffic, and walking profile.
    intersections.inintegerThe 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.outintegerThe 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.lanesarrayAn 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.durationnumberThe time required, in seconds, to traverse the intersection. Only available on the driving profile.
    intersections.tunnel_namestringThe 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_v8objectContains 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.classstringThe 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_urbanbooleanIndicates 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_indexintegerThe 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_stopobjectContains information about passing rest stops along the route. Only available on the driving profile.
    intersections.rest_stop.typestringThe 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). In Japan, rest_area and service_area correspond to PA and SA in the rest stop name, regardless of their amenities.
    intersections.rest_stop.namestringThe name of the rest stop. Optionally included if data is available.
    intersections.toll_collectionobjectContains 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.typestringThe 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.
    intersections.toll_collection.namestringThe name of toll collection point. Optionally included if data is available.
    intersections.railway_crossingbooleanIndicates whether there is a railway crossing at the intersection.
    intersections.traffic_signalbooleanIndicates whether there is a traffic signal at the intersection.
    intersections.stop_signbooleanIndicates whether there is a stop sign at the intersection.
    intersections.yield_signbooleanIndicates whether there is a yield sign at the intersection.
    speedLimitSignstringThe 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.
    speedLimitUnitstringThe 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,
    "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:

    PropertyTypeDescription
    bearing_beforeintegerA number between 0 and 360 indicating the clockwise angle from true north to the direction of travel before the maneuver.
    bearing_afterintegerA number between 0 and 360 indicating the clockwise angle from true north to the direction of travel after the maneuver.
    instructionstringA human-readable instruction of how to execute the returned maneuver.
    locationarrayThe coordinates of the maneuver as [longitude, latitude].
    modifierstringOptional. 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.
    If the source or target location is close enough to the depart or arrive location, no modifier will be supplied.
    typestringIndicates 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.

    Maneuver types

    typeDescription
    turnA 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 compared to the current direction of travel.
    arriveIndicates arrival to a destination of a leg. The modifier value indicates the position of the arrival point compared 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.
    forkKeep left or right side at a bifurcation, or left/right/straight at a trifurcation.
    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 like 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. It also contains 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.

    PropertyTypeDescription
    validbooleanIndicates whether a lane can be used to complete the maneuver (true) or not (false). For example, if a 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.
    activebooleanIndicates whether a 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_indicationstringWhen either the valid or active value is true, this property shows which of the lane indications applies 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 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.
    indicationsarrayThe indications (based on signs, road markings, or both) for a 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 sign is displayed
    straightA sign signaling to continue straight
    sharp leftA sign signaling a sharp left turn
    leftA sign signaling a left turn
    slight leftA sign signaling a slight left turn
    slight right A sign signaling a slight right turn
    rightA sign signaling a right turn
    sharp rightA sign signaling a sharp right turn
    uturnA sign signaling the possibility to reverse direction by making a u-turn
    access.designatedarrayIndicates whether a lane is designated to specified vehicle types. A vehicle type can be any of (but not limited to) bicycle, bus, hov, moped, motorcycle, or taxi. For example, when a lane is designated to buses and taxis, this field should have ["bus", "taxi"] as its value.

    Example lane object

    {
    "valid": true,
    "active": true,
    "valid_indication": "left",
    "indications": ["left"],
    "access": {
    "designated": ["bicycle", "bus"]
    }
    }

    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.

    PropertyTypeDescription
    distanceAlongGeometrynumberA float indicating how far from the upcoming maneuver the voice instruction should begin, in meters.
    announcementstringThe text of the verbal instruction.
    ssmlAnnouncementstringContains 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.

    PropertyTypeDescription
    distanceAlongGeometrynumberA 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.
    primaryobjectThe most important content to display to the user. This text is larger and at the top.
    secondaryobject or nullOptional. Additional content useful for visual guidance. This text is slightly smaller and below primary. Can be null.
    subobjectOptional. 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:

    PropertyTypeDescription
    textstringAll the text that should be displayed.
    typestringOptional. 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.
    modifierstringOptional. 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
    degreesintegerOptional. The degrees at which you will be exiting a roundabout, assuming 180 indicates going straight through the roundabout.
    driving_sidestringOptional. The side of the street on which people drive in that location. Can be left or right.
    componentsarrayAn array of objects 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.typestringContains 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 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.textstringThe sub-string of the text of the parent objects that may have additional context associated with it
    components.abbrstringOptional. 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_priorityintegerOptional. Indicates 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.imageBaseURLstringOptional. Points 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.png, @2x.png, or @3x.png to the URL string.
    components.directionsarrayOptional. Indicates 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.activebooleanOptional. Indicates whether the lane is recommended for performing the upcoming maneuver. If multiple lanes are active, all are equally recommended. Present if components.type is lane.
    components.active_directionstringOptional. When components.active is true, this property shows which of the lane's components.directions applies 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 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.

    PropertyTypeDescription
    idstringThe unique ID of the incident.
    typestringThe 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.
    descriptionstringA short description of the incident in a human-readable format.
    long_descriptionstringA long description of the incident in a human-readable format.
    creation_timestringThe time this incident was last created as an incident on the map in ISO-8601 format (for example, 2020-12-18T15:56:53Z). This value can change for the same incident between requests.
    start_timestringThe time this incident was started or is expected to start in ISO-8601 format (for example, 2020-12-18T15:56:53Z).
    end_timestringThe time this incident ended or is expected to end in ISO-8601 format (for example, 2020-12-18T15:56:53Z).
    impactstringThe impact of the incident on local traffic. Can be one of: unknown, critical, major, minor, low.
    lanes_blockedarrayLanes 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_blockedintegerThe number of items in the lanes_blocked array.
    congestionobjectContains information about the amount of congestion on the road around the incident.
    congestion.valueintegerA 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.
    closedbooleanIf this is true then the road has been completely closed.
    geometry_index_startintegerThe position in the coordinate list where the incident began, relative to the start of the leg it's on.
    geometry_index_endintegerThe position in the coordinate list where the incident ended, relative to the start of the leg it's on.
    sub_typestringThis could contain additional information about the type of incident.
    sub_type_descriptionstringThis could contain detail about the value of the sub_type field.
    iso_3166_1_alpha2stringThe two-letter ISO 3166-1 alpha-2 code for the country the incident is located in. Example: "US".
    iso_3166_1_alpha3stringThe three-letter ISO 3166-1 alpha-3 code for the country the incident is located in. Example: "USA".
    affected_road_namesarrayList of roads names affected by the incident. Alternate road names are separated by a /. The list is ordered from the first affected road to the last one that the incident affects.
    southnumberThe incident bounding box south latitude coordinate as float.
    westnumberThe incident bounding box west longitude coordinate as float.
    northnumberThe incident bounding box north latitude coordinate as float.
    eastnumberThe incident bounding box east longitude coordinate as float.

    Instructions languages

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

    CodeLanguageTextVoice
    ar or ar-AEArabic
    id or id-IDBahasa (Indonesia)
    cmn-CNChinese (Mandarin,Simplified)
    hr-HRCroatian
    cs or cs-CZCzech* contact sales
    da or da-DKDanish
    nl-BEDutch (Belgium)
    nl or nl-NLDutch (Holland)
    en-AUEnglish (Australia)en-GB
    en-GB-WLSEnglish (Welsh)en-GBen-GB
    en-GBEnglish (UK)
    en-INEnglish (India)en-GB
    en-SGEnglish (Singapore)
    en or en-USEnglish (United States)
    et or et-EEEstonian
    fi or fi-FIFinnish* contact sales
    fr-CAFrench (Canada)
    fr or fr-FRFrench (France)
    de or de-DEGerman (Germany
    de-CHGerman (Switzerland)de or de-DEde or de-DE
    el or el-GRGreek (Greece)* contact sales
    he or he-ILHebrew
    hu or hu-HUHungarian* contact sales
    is or is_ISIcelandic-
    it or it-ITItalian
    ja or ja-JPJapanese
    ko or ko-KRKorean
    lv-LVLatvian* contact sales
    lt or lt-LTLithuanian* contact sales
    no-NONorwegian-
    nb-NONorwegian (Bokmål)
    pl or pl-PLPolish
    pt-BRPortuguese (Brazil)
    pt or pt-PTPortuguese (Portugal)
    ro or ro-RORomanian
    ru or ru-RURussian
    sr or sr-RSSerbian (Cyrillic)* contact sales
    sk or sk-SKSlovak* contact sales
    sl or sl-SISlovene* contact sales
    es-MXSpanish (Latin America)
    es or es-ESSpanish (Spain)
    es-USSpanish (United States)es-MX
    sv or sv-SESwedish
    th-THThai
    tr or tr-TRTurkish
    uk or uk-UAUkrainian
    vi or vi-VNVietnamese
    • For access, contact us for more information. Premium voices available for de-de and nl-nl. To enable, contact us

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

    Notification object

    Beta support for notifications

    The notification object is included in the route leg object when making a mapbox/driving or mapbox/driving-traffic request in cases where there are warnings or safety messages, or important insights along the route.

    PropertyTypeDescription
    notifications.typestringThe type of notifications. Notification types supported are violation and alert. violation is more severe in nature and are delivered when user-set parameters (ex: exclude=unpaved) are violated during route generation. The severity of alert is less, and is intended to inform users when implicit preferences cannot be satisfied (ex: countryBorderCrossing). Available values are in the tables below.
    notifications.subtypestringThe optional subtype of notification. Available values are displayed in the tables below.
    notifications.geometry_indexintegerThe optional position in the coordinate list where the notification occurred, relative to the start of the leg it's on.
    notifications.geometry_index_startintegerThe optional position in the coordinate list where the notification began, relative to the start of the leg it's on.
    notifications.geometry_index_endintegerThe optional position in the coordinate list where the notification ended, relative to the start of the leg it's on.
    notifications.detailsobjectThe optional details specific to the notification type and subtype.
    notifications.details.requested_valuestringThe optional requested value in the request. For example, it is 3 (meters) if we specify max_width=3 in the request.
    notifications.details.actual_valuestringThe optional actual value associated with the property of the road. For example, it is 2.5 (meters) if maximum road width is 2.5 meters.
    notifications.details.unitstringThe optional unit of measure associated with details.actual_value and details.requested_value.
    notifications.details.messagestringThe optional message of the notification.

    If notifications.geometry_index_start and notifications.geometry_index_end is present, then the notification is related to a range on the leg geometry. If notifications.geometry_index is present, then the notification is related to a point on the leg geometry. Otherwise, the notification is not related to the leg geometry. Note that only the pair of notifications.geometry_index_start and notifications.geometry_index_end or notifications.geometry_index can be present in a single 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.

    Subtype

    DescriptionExample

    maxHeight

    The height of the vehicle is greater than the allowed height of the road. It is provided when max_height is specified.
    {
    "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."
    }
    }

    maxWidth

    The width of the vehicle is greater than the allowed width of the road. It is provided when max_width is specified.
    {
    "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."
    }
    }

    maxWeight

    The weight of the vehicle is greater than the allowed weight of the road. It is provided when max_weight is specified.
    {
    "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."
    }
    }

    unpaved

    Unpaved road, while it was explicitly requested to exclude unpaved roads from the route. It is provided when exclude=unpaved
    {
    "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)."
    }
    }

    pointExclusion

    Undesirable road, while it was explicitly requested to exclude a road from the route by point. It is provided when exclude=point(longitude latitude).
    {
    "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]."
    }
    }

    countryBorderCrossing

    Indicates a country border crossing. It is provided when exclude=country_border.
    {
    "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."
    }
    }

    stateBorderCrossing

    Indicates a state border crossing. It is provided when exclude=state_border.
    {
    "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."
    }
    }

    evMinChargeAtChargingStation

    Only applicable with engine=electric. EV's battery charge level was less than requested at a charging station. See ev_min_charge_at_charging_station EV routing parameter.
    {
    "type": "violation",
    "subtype": "evMinChargeAtChargingStation",
    "details": {
    "requested_value": 30000,
    "actual_value": 27000,
    "unit": "Wh"
    }
    }

    evMinChargeAtDestination

    Only applicable with engine=electric. EV's battery charge level was less than requested at the destination. See ev_min_charge_at_destination EV routing parameter.
    {
    "type": "violation",
    "subtype": "evMinChargeAtDestination",
    "details": {
    "requested_value": 20000,
    "actual_value": 13000,
    "unit": "Wh"
    }
    }

    Available alerts (notifications.type=alert)

    The severity of alert is less, and is intended to inform users when implicit preferences cannot be satisfied (ex: countryBorderCrossing).

    Subtype

    DescriptionExample

    countryBorderCrossing

    Indicates a country border crossing.
    {
    "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."
    }
    }

    stateBorderCrossing

    Indicates a state border crossing.
    {
    "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."
    }
    }

    evInsufficientCharge

    Only applicable with engine=electric. EV's battery charge level transitioned from a positive value to zero or less for the first time on a leg. Note that if a leg starts with zero charge level the notification is not emitted.
    {
    "type": "alert",
    "subtype": "evInsufficientCharge",
    "geometry_index": 3
    }

    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.
    Not Authorized - No Token401No token was used in the query.
    Not Authorized - Invalid Token401Check the access token you used in the query.
    Forbidden403There may be an issue with your account. Check your Account page for more details.

    In some cases, using an access tokens with URL restrictions can also result in a 403 error. For more information, see our Token management guide.
    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, 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. But, if using engine=electric, you can specify up to a total of 12 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.
    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.

    Was this page helpful?