Directions Api

Routing Direction Service (a.k.a. turn-by-turn), is an open-source routing service that lets you integrate routing and navigation into a web or mobile application.

The /directions endpoint calculates a route between two points (origin → destination).

use your token in Query Param:

POST /directions/?token=YOUR_TOKEN

Example Request

{ "locations": [ { "lat": "42.358528", "lon": "-83.271400" }, { "lat": "42.996613", "lon": "-78.749855" } ], "costing": "auto" ,"id":"my_work_route"}

There is an option to name your route request. You can do this by appending the following to your request &id=. The id is returned with the response so a user could match to the corresponding request.

Parameter	Location	Required	Description
token	Query Param	✅ Yes	API authentication token. Required, otherwise request will fail with 401 Token required.
locations	bodyjson	✅ Yes	Latitude,Longitude of the starting point to the destination point, "locations":[ { "lat": "42.358528", "lon": "-83.271400" }, { "lat": "42.996613", "lon": "-78.749855" } ],
costing	bodyjson	✅ Yes	"auto","bicycle","bus","truck","taxi","pedestrian"

Costing models

directions routing service uses dynamic, run-time costing to generate the route path. The route request must include the name of the costing model and can include optional parameters available for the chosen costing model.

Costing model	Description
auto	Standard costing for driving routes by car, motorcycle, truck, and so on that obeys automobile driving rules, such as access and turn restrictions. auto provides a short time path (though not guaranteed to be shortest time) and uses intersection costing to minimize turns and maneuvers or road name changes. Routes also tend to favor highways and higher classification roads, such as motorways and trunks.
bicycle	Standard costing for travel by bicycle, with a slight preference for using cycleways or roads with bicycle lanes. Bicycle routes follow regular roads when needed, but avoid roads without bicycle access.
bus	Standard costing for bus routes. Bus costing inherits the auto costing behaviors, but checks for bus access on the roads.
truck	Standard costing for trucks. Truck costing inherits the auto costing behaviors, but checks for truck access, width and height restrictions, and weight limits on the roads.
taxi	Standard costing for taxi routes. Taxi costing inherits the auto costing behaviors, but checks for taxi lane access on the roads and favors those roads.
motor_scooter	Standard costing for travel by motor scooter or moped. By default, motor_scooter costing will avoid higher class roads unless the country overrides allows motor scooters on these roads. Motor scooter routes follow regular roads when needed, but avoid roads without motor_scooter, moped, or mofa access.
pedestrian	Standard walking route that excludes roads without pedestrian access. In general, pedestrian routes are shortest distance with the following exceptions: walkways and footpaths are slightly favored, while steps or stairs and alleys are slightly avoided.

Trip legs and maneuvers

A trip contains one or more legs. For n number of break locations, there are n-1 legs.
Through locations do not create separate legs.

Each leg of the trip includes a summary, which is comprised of the same information as a trip summary but applied to the single leg of the trip. It also includes a shape, which is an encoded polyline of the route path (with 6 digits decimal precision), and a list of maneuvers as a JSON array.

For more about decoding route shapes, see these code examples.

If elevation_interval is specified, each leg of the trip will return elevation along the route as a JSON array. The elevation_interval is also returned.
Units for both elevation and elevation_interval are either meters or feet based on the input units specified.

---

Each maneuver includes

Maneuver item	Description
type	Type of maneuver. See below for a list.
instruction	Written maneuver instruction. Describes the maneuver, such as "Turn right onto Main Street".
verbal_transition_alert_instruction	Text suitable for use as a verbal alert in a navigation application. The transition alert instruction will prepare the user for the forthcoming transition. Example: "Turn right onto North Prince Street".
verbal_pre_transition_instruction	Text suitable for use as a verbal message immediately prior to the maneuver transition. Example: "Turn right onto North Prince Street, U.S. 2 22".
verbal_post_transition_instruction	Text suitable for use as a verbal message immediately after the maneuver transition. Example: "Continue on U.S. 2 22 for 3.9 miles".
street_names	List of street names that are consistent along the entire nonobvious maneuver.
begin_street_names	When present, these are the street names at the beginning (transition point) of the nonobvious maneuver (if they are different than the names that are consistent along the entire nonobvious maneuver).
time	Estimated time along the maneuver in seconds.
length	Maneuver length in the units specified.
begin_shape_index	Index into the list of shape points for the start of the maneuver.
end_shape_index	Index into the list of shape points for the end of the maneuver.
toll	true if the maneuver has any toll, or portions of the maneuver are subject to a toll.
highway	true if a highway is encountered on this maneuver.
rough	true if the maneuver is unpaved or rough pavement, or has any portions that have rough pavement.
gate	true if a gate is encountered on this maneuver.
ferry	true if a ferry is encountered on this maneuver.
sign	Contains the interchange guide information at a road junction associated with this maneuver. See below for details.
roundabout_exit_count	The spoke to exit roundabout after entering.
depart_instruction	Written depart time instruction. Typically used with a transit maneuver, such as "Depart: 8:04 AM from 8 St - NYU".
verbal_depart_instruction	Text suitable for use as a verbal depart time instruction. Typically used with a transit maneuver, such as "Depart at 8:04 AM from 8 St - NYU".
arrive_instruction	Written arrive time instruction. Typically used with a transit maneuver, such as "Arrive: 8:10 AM at 34 St - Herald Sq".
verbal_arrive_instruction	Text suitable for use as a verbal arrive time instruction. Typically used with a transit maneuver, such as "Arrive at 8:10 AM at 34 St - Herald Sq".
transit_info	Contains the attributes that describe a specific transit route. See below for details.
verbal_multi_cue	true if the verbal_pre_transition_instruction has been appended with the verbal instruction of the next maneuver.
travel_mode	Travel mode: • "drive" • "pedestrian" • "bicycle" • "transit"
travel_type	Travel type for drive: • "car" • "motorcycle" • "motor_scooter" • "truck" • "bus" Travel type for pedestrian: • "foot" • "wheelchair" Travel type for bicycle: • "road" • "hybrid" • "cross" • "mountain" Travel type for transit: • Tram or light rail = "tram" • Metro or subway = "metro" • Rail = "rail" • Bus = "bus" • Ferry = "ferry" • Cable car = "cable_car" • Gondola = "gondola" • Funicular = "funicular"
bss_maneuver_type	Used when travel_mode is bikeshare. Describes bike share maneuver. The default value is "NoneAction". Options: • "NoneAction" • "RentBikeAtBikeShare" • "ReturnBikeAtBikeShare"
bearing_before	The clockwise angle from true north to the direction of travel immediately before the maneuver.
bearing_after	The clockwise angle from true north to the direction of travel immediately after the maneuver.
lanes	An array describing lane-level guidance. Used when turn_lanes is enabled. See below for details.

Directions Options

Directions options should be specified at the top level of the JSON object.

Options	Description
units	Distance units for output. Allowable unit types are miles (or mi) and kilometers (or km). If no unit type is specified, the units default to kilometers.
language	The language of the narration instructions based on the IETF BCP 47 language tag string. If no language is specified or the specified language is unsupported, United States-based English (en-US) is used. Currently supported language list.
directions_type	An enum with 3 values: - none indicating no maneuvers or instructions should be returned. - maneuvers indicating that only maneuvers be returned. - instructions indicating that maneuvers with instructions should be returned (this is the default if not specified).
format	Four options are available: - json is default Valhalla routing directions JSON format. - gpx returns the route as a GPX (GPS exchange format) XML track. - osrm creates an OSRM compatible route directions JSON. - pbf formats the result using protocol buffers.
shape_format	If "format": "osrm" is set: Specifies the optional format for the path shape of each connection. One of polyline6 (default), polyline5, geojson or no_shape.
banner_instructions	If the format is osrm, this boolean indicates if each step should have the additional bannerInstructions attribute, which can be displayed in some navigation system SDKs.
voice_instructions	If the format is osrm, this boolean indicates if each step should have the additional voiceInstructions attribute, which can be heard in some navigation system SDKs.
alternates	A number denoting how many alternate routes should be provided. There may be no alternates or less alternates than the user specifies. Alternates are not yet supported on multipoint routes (that is, routes with more than 2 locations). They are also not supported on time dependent routes.

---

Example with language

{"locations":[{"lat":40.730930,"lon":-73.991379},{"lat":40.749706,"lon":-73.991562}],"format":"osrm","costing":"bus","banner_instructions":true,"voice_instructions":true,"language":"es-ES"}

Supported Language Tags

Language tag	Language alias	Description
bg-BG	bg	Bulgarian (Bulgaria)
ca-ES	ca	Catalan (Spain)
cs-CZ	cs	Czech (Czech Republic)
da-DK	da	Danish (Denmark)
de-DE	de	German (Germany)
el-GR	el	Greek (Greece)
en-GB	en	English (United Kingdom)
en-US-x-pirate	en-x-pirate	English (United States) Pirate
en-US	en	English (United States)
es-ES	es	Spanish (Spain)
et-EE	et	Estonian (Estonia)
fi-FI	fi	Finnish (Finland)
fr-FR	fr	French (France)
hi-IN	hi	Hindi (India)
hu-HU	hu	Hungarian (Hungary)
it-IT	it	Italian (Italy)
ja-JP	ja	Japanese (Japan)
nb-NO	nb	Bokmål (Norway)
nl-NL	nl	Dutch (Netherlands)
pl-PL	pl	Polish (Poland)
pt-BR	pt	Portuguese (Brazil)
pt-PT	pt	Portuguese (Portugal)
ro-RO	ro	Romanian (Romania)
ru-RU	ru	Russian (Russia)
sk-SK	sk	Slovak (Slovakia)
sl-SI	sl	Slovenian (Slovenia)
sv-SE	sv	Swedish (Sweden)
tr-TR	tr	Turkish (Turkey)
uk-UA	uk	Ukrainian (Ukraine)

Outputs of a route

The route results are returned as a trip. This is a JSON object that contains details about the trip, including locations, a summary with basic information about the entire trip, and a list of legs.

Trip item	Description
status	Status code.
status_messa	Status message.
units	The specified units of length are returned, either kilometers or miles.
language	The language of the narration instructions. If the user specified a language in the directions options and the specified language was supported - this returned value will be equal to the specified value. Otherwise, this value will be the default (en-US) language.
locations	Location information is returned in the same form as it is entered with additional fields to indicate the side of the street.
warnings (optional)	This array may contain warning objects informing about deprecated request parameters, clamped values etc.