Directions
Point-to-point routes with geometry and turn instructions.
Route between two points
The simplest form: a start and an end, each as lon,lat, and a GeoJSON route back.
You can send the key as api_key in the query string. Every endpoint that needs a key
accepts it.
The Authorization header is safer, though: a key in a URL ends up in logs.
path Parameters
profileThe routing profile. Only driving-car is served. Any other value returns an
"incorrect value" error.
query Parameters
startStart coordinate as lon,lat.
endEnd coordinate as lon,lat.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Route between two points › Responses
A route, as GeoJSON.
Route with full options
Returns a route as JSON, with the route's shape as an encoded polyline: the points along the
route compressed into a single line of text. If you need the points themselves, the /geojson
form of this endpoint returns them already decoded.
What it costs
10 elements per request, however many waypoints it has.
Limits
A waypoint is a point the route must pass through, in order, including its start and its end. A route can have up to 50 waypoints.
The longest route depends on the options you send:
| Request | Longest route |
|---|---|
| An ordinary route | 6,000 km |
With options.avoid_polygons | 100 km |
| With dynamic weights | 100 km |
Requests that avoid areas with options.avoid_polygons, or that use dynamic weights, are much
slower to compute, which is why their limit is lower.
Errors
Going over a limit returns 400 (code 2004), and the message says which limit.
path Parameters
profileThe routing profile. Only driving-car is served. Any other value returns an
"incorrect value" error.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Route with full options › Request Body
coordinatesThe waypoints, in order, starting at the origin.
preferenceunitslanguageLanguage for turn instructions.
instructionsInclude turn-by-turn instructions. Default true.
instructions_formatgeometryInclude the route geometry. Default true.
geometry_simplifyelevationextra_infoattributescontinue_straightalternative_routesRequest alternative routes.
optionsAdvanced routing options such as avoid_features or avoid_polygons.
Note: requests with options are much slower to compute, and have a much lower
limit on route distance.
radiusesbearingsmaximum_speedsuppress_warningsidRoute with full options › Responses
The computed route.
bboxDetails about the request and the data behind the answer, plus element_count.
Route, JSON form
Identical to POST /v2/directions/{profile}, with the format in the path.
path Parameters
profileThe routing profile. Only driving-car is served. Any other value returns an
"incorrect value" error.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Route, JSON form › Request Body
coordinatesThe waypoints, in order, starting at the origin.
preferenceunitslanguageLanguage for turn instructions.
instructionsInclude turn-by-turn instructions. Default true.
instructions_formatgeometryInclude the route geometry. Default true.
geometry_simplifyelevationextra_infoattributescontinue_straightalternative_routesRequest alternative routes.
optionsAdvanced routing options such as avoid_features or avoid_polygons.
Note: requests with options are much slower to compute, and have a much lower
limit on route distance.
radiusesbearingsmaximum_speedsuppress_warningsidRoute, JSON form › Responses
The computed route.
bboxDetails about the request and the data behind the answer, plus element_count.
Route, GeoJSON form
The same route as a GeoJSON FeatureCollection,
with the geometry already decoded, ready for a map library.
path Parameters
profileThe routing profile. Only driving-car is served. Any other value returns an
"incorrect value" error.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Route, GeoJSON form › Request Body
coordinatesThe waypoints, in order, starting at the origin.
preferenceunitslanguageLanguage for turn instructions.
instructionsInclude turn-by-turn instructions. Default true.
instructions_formatgeometryInclude the route geometry. Default true.
geometry_simplifyelevationextra_infoattributescontinue_straightalternative_routesRequest alternative routes.
optionsAdvanced routing options such as avoid_features or avoid_polygons.
Note: requests with options are much slower to compute, and have a much lower
limit on route distance.
radiusesbearingsmaximum_speedsuppress_warningsidRoute, GeoJSON form › Responses
The computed route, as GeoJSON.
Route, GPX form
The same route as GPX XML.
This response isn't JSON, so it doesn't include the element_count field the JSON forms add.
The attribution is in the GPX metadata.
path Parameters
profileThe routing profile. Only driving-car is served. Any other value returns an
"incorrect value" error.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Route, GPX form › Request Body
coordinatesThe waypoints, in order, starting at the origin.
preferenceunitslanguageLanguage for turn instructions.
instructionsInclude turn-by-turn instructions. Default true.
instructions_formatgeometryInclude the route geometry. Default true.
geometry_simplifyelevationextra_infoattributescontinue_straightalternative_routesRequest alternative routes.
optionsAdvanced routing options such as avoid_features or avoid_polygons.
Note: requests with options are much slower to compute, and have a much lower
limit on route distance.
radiusesbearingsmaximum_speedsuppress_warningsidRoute, GPX form › Responses
The computed route, as GPX.