This product is in Legacy status. As of October 2026, Directions API (Legacy) can no longer be enabled for new Google Cloud projects. Existing projects remain fully supported. For new features and improved performance, migrate to the Routes API.
Example requests
The following request returns driving directions from Toronto, Ontario to Montreal, Quebec.
URL
https://maps.googleapis.com/maps/api/directions/json?destination=Montreal &origin=Toronto &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY'
By changing the mode and avoid parameters,
the initial request can be modified to return directions for a
scenic bicycle journey that avoids major highways.
URL
https://maps.googleapis.com/maps/api/directions/json ?avoid=highways &destination=Montreal &mode=bicycling &origin=Toronto &key=YOUR_API_KEYYOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY'YOUR_API_KEY'
The following request searches for transit directions from Brooklyn, New York
to Queens, New York. The request does not specify a
departure_time, so the departure time defaults to the current
time:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Queens &mode=transit &origin=Brooklyn &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&keyYOUR_API_KEY'
The following transit request includes a specific departure time.
Note: In this example the departure time is specified as July 30, 2012 at 09:45 am. To avoid an error, you must change the parameter to a time in the future before submitting the request.
URL
https://maps.googleapis.com/maps/api/directions/json ?departure_time=1343641500 &destination=Queens &mode=transit &origin=Brooklyn &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&departure_time=1343641500&key=YOUR_API_KEY'
The following request uses plus codes to return driving directions from H8MW+WP to GCG2+3M in Kolkata, India.
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=GCG2%2B3M%20Kolkata%20India &origin=H8MW%2BWP%20Kolkata%20India &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=H8MW%2BWP%20Kolkata%20India&destination=GCG2%2B3M%20Kolkata%20India&key=YOUR_API_KEY'
The following request returns driving directions from Glasgow, UK to Perth, UK using place IDs.
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=place_id%3AChIJA01I-8YVhkgRGJb0fW4UX7Y &origin=place_id%3AChIJ685WIFYViEgRHlHvBbiD5nE &keyYOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=place_id%3AChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id%3AChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY'
Travel modes
When you calculate directions, you may specify
the transportation mode to use. By default,
directions are calculated as driving directions. The following
travel modes are supported:
driving(default) indicates standard driving directions using the road network.walkingrequests walking directions via pedestrian paths & sidewalks (where available).bicyclingrequests bicycling directions via bicycle paths & preferred streets (where available).transitrequests directions via public transit routes (where available). If you set the mode totransit, you can optionally specify either adeparture_timeor anarrival_time. If neither time is specified, thedeparture_timedefaults to now (that is, the departure time defaults to the current time). You can also optionally include atransit_modeand/or atransit_routing_preference.
Note: Both walking and
bicycling directions may sometimes not include clear pedestrian or
bicycling paths, so these directions will return warnings
in the returned result which you must display to the user.
Traffic information
Traffic information is used when all of the following apply (these are the
conditions required to receive the
duration_in_traffic field in the Directions response):
- The
travel
modeparameter isdriving, or is not specified (drivingis the default travel mode). - The request includes a valid
departure_timeparameter. Thedeparture_timecan be set to the current time or some time in the future. It cannot be in the past. - The request does not include stopover
waypoints. If the request
includes waypoints, prefix each waypoint with
via:to influence the route but avoid stopovers. For example,&waypoints=via:San Francisco|via:Mountain View|...
Optionally, you can include the
traffic_model parameter in your request to specify the assumptions to use when
calculating time in traffic.
The following URL initiates a Directions request for a journey from Boston, MA to
Concord, MA, via Charlestown and Lexington. The request includes a departure time, meeting
all the requirements to return the duration_in_traffic field in the Directions
response.
URL
https://maps.googleapis.com/maps/api/directions/json ?departure_time=now &destination=Concord%2C%20MA &origin=Boston%2C%20MA &waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Boston%2C%20MA&destination=Concord%2C%20MA&waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA&departure_time=now&key=YOUR_API_KEY'
Waypoints
When calculating routes using the Directions API (Legacy), you may specify waypoints to return a route that includes pass throughs or stopovers at intermediate locations. You can add waypoints to driving, walking or bicycling directions but not transit directions.
Specify locations in the waypoints parameter.
You can supply one or more locations separated by the pipe character
(| or %7C), in the form of a place ID, an address, or latitude/longitude
coordinates. By default, the Directions service calculates a route using the waypoints in the order
they are given. The precedence for parsing the value of the waypoint is place ID, latitude/longitude
coordinates, then address.
- If you pass a place ID, you must prefix it with
place_id:. You can retrieve place IDs from the Geocoding API and the Places API (including Place Autocomplete). For an example using place IDs from Place Autocomplete, see Place Autocomplete and Directions. For more about place IDs, see the Place ID overview.For efficiency and accuracy, use place ID's when possible. These ID's are uniquely explicit like a lat/lng value pair and provide geocoding benefits for routing such as access points and traffic variables. Unlike an address, ID's don't require the service to perform a search or an intermediate request for place details; therefore, performance is better.
- If you pass latitude/longitude coordinates, the values go directly to the frontend server
to calculate directions without geocoding. The points are snapped to roads and might not provide
the accuracy your app needs. Use coordinates when you are confident the values truly specify the
points your app needs for routing without regard to possible access points or additional geocoding
details. Ensure that a comma (
%2C) and not a space (%20) separates the latitude and longitude values. - If you pass an address, the Directions service will geocode the string and convert it into latitude/longitude coordinates to calculate directions. If the address value is ambiguous, the value might evoke a search to disambiguate from similar addresses. For example, "1st Street" could be a complete value or a partial value for "1st street NE" or "1st St SE". This result may be different from that returned by the Geocoding API. You can avoid possible misinterpretations using place IDs. See troubleshooting the results of my route request.
Alternatively, you can supply an encoded set of points using the Encoded Polyline Algorithm. You will find an encoded set is useful for a large number of waypoints, because the URL is significantly shorter. All web services have a URL limit of 16384 characters.
- Encoded polylines must be prefixed with
enc:and followed by a colon (:). For example:waypoints=enc:gfo}EtohhU:. - You can also include multiple encoded polylines, separated by the pipe
character (
|). For example,waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:
The following URL initiates a Directions request for a journey between Boston, MA and Concord, MA with stopovers in Charlestown and Lexington, in that order. The example uses addresses:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Concord%2C%20MA &origin=Boston%2C%20MA &waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Boston%2C%20MA&destination=Concord%2C%20MA&waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA&key=YOUR_API_KEY'
Influence routes with stopover and pass through points
For each waypoint in the request, the directions response appends an
entry to the legs array to provide the
details for stopovers on that leg of the journey.
If you'd like to influence the route using waypoints without adding a
stopover, add the prefix via: to the waypoint. Waypoints
prefixed with via: won't add an entry to the
legs array, but will route the journey
through the waypoint.
The following URL modifies the previous request such that the journey is routed through Lexington without stopping:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Concord%2C%20MA &origin=Boston%2C%20MA &waypoints=Charlestown%2CMA%7Cvia%3ALexington%2CMA &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Boston%2C%20MA&destination=Concord%2C%20MA&waypoints=Charlestown%2CMA%7Cvia%3ALexington%2CMA&key=YOUR_API_KEY'
The via: prefix is most effective when creating routes
in response to the user dragging the waypoints on the map. Doing so allows
the user to see how the final route may look in real-time and helps ensure that
waypoints are placed in locations that are accessible to the Directions API (Legacy).
The following URL requests waypoints using latitude/longitude coordinates:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Perth%2C%20AU &origin=Sydney%2C%20AU &waypoints=via%3A-37.81223%2C144.96254%7Cvia%3A-34.92788%2C138.60008 &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Sydney%2C%20AU&destination=Perth%2C%20AU&waypoints=via%3A-37.81223%2C144.96254%7Cvia%3A-34.92788%2C138.60008&key=YOUR_API_KEY'
Here is the same request, using an encoded polyline:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Perth%2C%20AU &origin=Sydney%2C%20AU &waypoints=via%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Sydney%2C%20AU&destination=Perth%2C%20AU&waypoints=via%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A&key=YOUR_API_KEY'
Note that you can freely intermix a via: specifier with location modifiers.
For example:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Perth%2C%20AU &origin=Sydney%2C%20AU &waypoints=side_of_road%3Avia%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Sydney%2C%20AU&destination=Perth%2C%20AU&waypoints=side_of_road%3Avia%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A&key=YOUR_API_KEY'
Optimize your waypoints
By default, the Directions service calculates a route through
the provided waypoints in their given order. Optionally, you
may pass optimize:true as the first argument
within the waypoints parameter to allow the Directions
service to optimize the provided route by rearranging the waypoints in
a more efficient order. (This optimization is an application of the
traveling salesperson problem.) Travel time is the primary factor which is
optimized, but other factors such as distance, number of turns and many more
may be taken into account when deciding which route is the most efficient. All
waypoints must be stopovers for the Directions service to optimize their
route.
If you instruct the Directions service to optimize the order of
its waypoints, their order will be returned in the
waypoint_order field within the
routes object.
The waypoint_order field
returns values which are zero-based.
The following example calculates a road journey from Adelaide, South Australia to each of South Australia's main wine regions using route optimization.
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Adelaide%2C%20SA &origin=Adelaide%2C%20SA &waypoints=optimize%3Atrue%7CBarossa%20Valley%2C%20SA%7CClare%2C%20SA%7CConnawarra%2C%20SA%7CMcLaren%20Vale%2C%20SA &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide%2C%20SA&destination=Adelaide%2C%20SA&waypoints=optimize%3Atrue%7CBarossa%20Valley%2C%20SA%7CClare%2C%20SA%7CConnawarra%2C%20SA%7CMcLaren%20Vale%2C%20SA&key=YOUR_API_KEY'
Inspection of the calculated route will indicate that calculation uses waypoints in the following waypoint order:
"waypoint_order": [ 3, 2, 0, 1 ]
Restrictions
Directions may be calculated that adhere to certain restrictions. Restrictions
are indicated by use of the avoid parameter, and an argument to that
parameter indicating the restriction to avoid. The following restrictions are supported:
avoid=tollsavoid=highwaysavoid=ferries
It's possible to request a route that avoids any combination of tolls, highways and ferries by
passing both restrictions to the avoid parameter. For example:
avoid=tolls|highways|ferries.
Note: the addition of restrictions does not preclude routes that include the restricted feature; it biases the result to more favorable routes.
Unit systems
Directions results contain text within distance
fields that may be displayed to the user to indicate the distance of a
particular "step" of the route. By default, this text uses the unit system
of the origin's country or region.
For example, a route from
"Chicago, IL" to "Toronto, ONT" will display results in miles, while
the reverse route will display results in kilometers. You
may override this unit system by setting one explicitly within the
request's units parameter, passing one of the following
values:
metricspecifies usage of the metric system. Textual distances are returned using kilometers and meters.imperialspecifies usage of the Imperial (English) system. Textual distances are returned using miles and feet.
Note: this unit system setting only
affects the text displayed within distance
fields. The distance fields also contain values
which are always expressed in meters.
Region biasing
You can set the Directions service to return results from a
specific region by using the region parameter. This parameter
takes a two-character ccTLD
(country code top-level domain) argument specifying the region bias. Most ccTLD
codes are identical to ISO 3166-1 alpha-2 codes, with some notable exceptions.
For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its
ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of
Great Britain and Northern Ireland"). See Google Maps Platform
Coverage Details for supported regions.
You may utilize any domain in which the main Google Maps application has launched driving directions.
For example, a directions request for "Toledo" to "Madrid"
returns appropriate results when region is set to es
and "Toledo" is then interpreted as the Spanish city:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Madrid &origin=Toledo ®ion=es &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid®ion=es&key=YOUR_API_KEY'
JSON
{ "geocoded_waypoints": [ { "geocoder_status": "OK", "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y", "types": ["locality", "political"], }, { "geocoder_status": "OK", "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ", "types": ["locality", "political"], }, ], "routes": [ { "bounds": { "northeast": { "lat": 40.4165207, "lng": -3.7026134 }, "southwest": { "lat": 39.862808, "lng": -4.029406799999999 }, }, "copyrights": "Map data ©2022 Inst. Geogr. Nacional", "legs": [ { "distance": { "text": "74.3 km", "value": 74327 }, "duration": { "text": "57 mins", "value": 3446 }, "end_address": "Madrid, Spain", "end_location": { "lat": 40.4165207, "lng": -3.705076 }, "start_address": "Toledo, Spain", "start_location": { "lat": 39.862808, "lng": -4.0273727 }, "steps": [ { "distance": { "text": "0.6 km", "value": 615 }, "duration": { "text": "2 mins", "value": 106 }, "end_location": { "lat": 39.8681019, "lng": -4.029378299999999 }, "html_instructions": "Head <b>northwest</b> on <b>Av. de la Reconquista</b> toward <b>C. de la Diputación</b>", "polyline": { "points": "quhrF`rqWCBQJUJm@PQFg@Ni@JeBh@}@XaD|@{@Vk@Ns@RUFoA^u@R_AXwA`@WHMBG@C?E?GAC?IC", }, "start_location": { "lat": 39.862808, "lng": -4.0273727 }, "travel_mode": "DRIVING", }, // Additional steps omitted for brevity ], "traffic_speed_entry": [], "via_waypoint": [], }, ], "overview_polyline": { "points": "quhrF`rqWcHzBaNzDeG~A][?k@lA{Dr@mBR]HmA[WQDWE[g@mAeE... (truncated for brevity)", }, "summary": "A-42", "warnings": [], "waypoint_order": [], }, ], "status": "OK", }
XML
<DirectionsResponse> <status>OK</status> <route> <summary>A-42</summary> <leg> <step> <travel_mode>DRIVING</travel_mode> <start_location> <lat>39.8628080</lat> <lng>-4.0273727</lng> </start_location> <end_location> <lat>39.8681019</lat> <lng>-4.0293783</lng> </end_location> <polyline> <points>quhrF`rqWCBQJUJm@PQFg@Ni@JeBh@}@XaD|@{@Vk@Ns@RUFoA^u@R_AXwA`@WHMBG@C?E?GAC?IC</points> </polyline> <duration> <value>106</value> <text>2 mins</text> </duration> <html_instructions>Head <b>northwest</b> on <b>Av. de la Reconquista</b> toward <b>C. de la Diputación</b></html_instructions> <distance> <value>615</value> <text>0.6 km</text> </distance> </step> <!-- Additional steps omitted for brevity --> <duration> <value>3446</value> <text>57 mins</text> </duration> <distance> <value>74327</value> <text>74.3 km</text> </distance> <start_location> <lat>39.8628080</lat> <lng>-4.0273727</lng> </start_location> <end_location> <lat>40.4165207</lat> <lng>-3.7050760</lng> </end_location> <start_address>Toledo, Spain</start_address> <end_address>Madrid, Spain</end_address> </leg> <copyrights>Map data ©2022 Inst. Geogr. Nacional</copyrights> <overview_polyline> <points>quhrF`rqWcHzBaNzDeG~A][?k@lA{Dr@mBR]HmA[WQDWE[g@mAeE... (truncated for brevity)</points> </overview_polyline> <bounds> <southwest> <lat>39.8628080</lat> <lng>-4.0294068</lng> </southwest> <northeast> <lat>40.4165207</lat> <lng>-3.7026134</lng> </northeast> </bounds> </route> <geocoded_waypoint> <geocoder_status>OK</geocoder_status> <type>locality</type> <type>political</type> <place_id>ChIJ8f21C60Lag0R_q11auhbf8Y</place_id> </geocoded_waypoint> <geocoded_waypoint> <geocoder_status>OK</geocoder_status> <type>locality</type> <type>political</type> <place_id>ChIJgTwKgJcpQg0RaSKMYcHeNsQ</place_id> </geocoded_waypoint> </DirectionsResponse>
A directions request for "Toledo" to "Madrid" sent without a region
parameter does not return results, because "Toledo" is interpreted as the
city in Ohio and not Spain:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=Madrid &origin=Toledo &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY'
JSON
{ "geocoded_waypoints": [ { "geocoder_status": "OK", "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "types": ["locality", "political"], }, { "geocoder_status": "OK", "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ", "types": ["locality", "political"], }, ], "routes": [], "status": "ZERO_RESULTS", }
XML
<DirectionsResponse> <status>ZERO_RESULTS</status> <geocoded_waypoint> <geocoder_status>OK</geocoder_status> <type>locality</type> <type>political</type> <place_id>ChIJeU4e_C2HO4gRRcM6RZ_IPHw</place_id> </geocoded_waypoint> <geocoded_waypoint> <geocoder_status>OK</geocoder_status> <type>locality</type> <type>political</type> <place_id>ChIJgTwKgJcpQg0RaSKMYcHeNsQ</place_id> </geocoded_waypoint> </DirectionsResponse>
Location Modifiers
You can use location modifiers to indicate how drivers should approach a
particular location, by using the side_of_road parameter to specify
which side of the road to use, or by specifying a heading to indicate the
correct direction of travel. These modifiers may be freely mixed with the
via: modifier for intermediate waypoints.
Specify that routes must pass through a particular side of the road
When specifying a waypoint, you can request that the route go through whichever
side of the road the waypoint is biased towards by using the side_of_road:
prefix. For example, this directions request will return a long route so that the
vehicle ends on the side of the road to which the waypoint was biased:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=side_of_road%3A37.7663444%2C-122.4412006 &origin=37.7680296%2C-122.4375126 &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=37.7680296%2C-122.4375126&destination=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'
When using side_of_road: with encoded polylines, the parameter is
applied to every location along the polyline.
The side_of_road: modifier may only be used with the following
restrictions:
- The
travel
modeparameter isdriving, or is not specified (drivingis the default travel mode).
Specify that routes should have a particular heading
When specifying a waypoint, you can request that the route go through the
waypoint in a particular heading. This heading is specified
with the prefix heading=X:, where X is an integer degree value
between 0 (inclusive) and 360 (exclusive). A heading of 0 indicates North, 90
indicates East, continuing clockwise. For example, in this directions
request the route goes east from the origin, then takes a U-turn:
URL
https://maps.googleapis.com/maps/api/directions/json ?destination=37.773245%2C-122.469502 &origin=heading%3D90%3A37.773279%2C-122.468780 &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=heading%3D90%3A37.773279%2C-122.468780&destination=37.773245%2C-122.469502&key=YOUR_API_KEY'
The heading=X: modifier may only be used with the
following restrictions:
- The
travel
modeparameter isdriving,bicycling, or is not specified (drivingis the default travel mode). - The
side_of_roadmodifier is not specified for the same location. - The location is specified with a latitude/longitude value. You may not use
headingwith addresses, Place IDs, or encoded polylines.