The Google Directions API

Introduction

The Google Directions API is a service that calculates directions between locations using an HTTP request. Directions may specify origins, destinations and waypoints either as text strings (e.g. "Chicago, IL" or "Darwin, NT, Australia") or as latitude/longitude coordinates. The Directions API can return multi-part directions using a series of waypoints.

This service is generally designed for calculating directions for static (known in advance) addresses for placement of application content on a map; this service is not designed to respond in real time to user input, for example. For dynamic directions calculations (for example, within a user interface element), consult the documentation for the JavaScript API V3 Directions Service.

Calculating directions is a time and resource intensive task. Whenever possible, calculate known addresses ahead of time (using the service described here) and store your results in a temporary cache of your own design.

Audience

This document is intended for website and mobile developers who want to use compute direction data within maps provided by one of the Google Maps APIs. It provides an introduction to using the API and reference material on the available parameters.

Usage Limits

Use of the Google Directions API is subject to a query limit of 2,500 directions requests per day. Individual directions requests may contain up to 8 intermediate waypoints in the request. Google Maps API for Business customers may query up to 100,000 directions requests per day, with up to 23 waypoints allowed in each request.

Additionally, note that Directions API URLs are restricted to 2048 characters, before URL Encoding. As some Directions service URLs may involve many locations along a path, be aware of this limit when constructing your URLs.

Note: the Directions API may only be used in conjunction with displaying results on a Google map; using Directions data without displaying a map for which directions data was requested is prohibited. Additionally, calculation of directions generates copyrights and warnings which must be displayed to the user in some fashion. For complete details on allowed usage, consult the Maps API Terms of Service License Restrictions.

Directions Requests

A Directions API request takes the following form:

http://maps.googleapis.com/maps/api/directions/output?parameters

where output may be either of the following values:

• json (recommended) indicates output in JavaScript Object Notation (JSON)
• xml indicates output as XML

To access the Directions API over HTTPS, use:

https://maps.googleapis.com/maps/api/directions/output?parameters

HTTPS is recommended for applications that include sensitive user data, such as a user's location, in requests.

Request Parameters

Certain parameters are required while others are optional. As is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

The Directions API defines a directions request using the following URL parameters:

• origin (required) — The address or textual latitude/longitude value from which you wish to calculate directions. *
• destination (required) — The address or textual latitude/longitude value from which you wish to calculate directions.*
• mode (optional, defaults to driving) — specifies what mode of transport to use when calculating directions. Valid values are specified in Travel Modes.

• waypoints (optional) specifies an array of waypoints. Waypoints alter a route by routing it through the specified location(s). A waypoint is specified as either a latitude/longitude coordinate or as an address which will be geocoded. (For more information on waypoints, see Using Waypoints in Routes below.)

• alternatives (optional), if set to true, specifies that the Directions service may provide more than one route alternative in the response. Note that providing route alternatives may increase the response time from the server.

• avoid (optional) indicates that the calculated route(s) should avoid the indicated features. Currently, this parameter supports the following two arguments:

  • tolls indicates that the calculated route should avoid toll roads/bridges.
  • highways indicates that the calculated route should avoid highways.

  (For more information see Route Restrictions below.)

• units (optional) — specifies what unit system to use when displaying results. Valid values are specified in Unit Systems below.

• region (optional) — The region code, specified as a ccTLD ("top-level domain") two-character value. (For more information see Region Biasing below.)
• sensor (required) — Indicates whether or not the directions request comes from a device with a location sensor. This value must be either true or false.

* Note: You may pass either an address or a latitude/longitude coordinate in several parameters. If you pass an address as a string, the Directions service will geocode the string and convert it to a latitude-longitude coordinate to calculate directions. If you pass coordinates, ensure that no space exists between the latitude and longitude values.

Travel Modes

When you calculate directions, you may specify which transportation mode to use. By default, directions are calculated as driving directions. The following travel modes are currently supported:

• driving (default) indicates standard driving directions using the road network.
• walking requests walking directions via pedestrian paths & sidewalks (where available).
• bicycling requests bicycling directions via bicycle paths & preferred streets (currently only available in the US).

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.

Using Waypoints in Routes

When calculating routes using the Directions API, you may also specify waypoints. Waypoints allow you to calculate routes through additional locations, in which case the returned route passes through the given waypoints.

Waypoints are specified within the waypoints parameter and consist of one or more addresses or locations separated by the pipe (|) character.

For example, the following URL initiates a Directions request for a route between Boston, MA and Concord, MA via Charlestown and Lexington, in that order:

http://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&sensor=false

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 Travelling Salesman Problem.)

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 trip route from Adelaide, South Australia to each of South Australia's main wine regions using route optimization.

http://maps.googleapis.com/maps/api/directions/json?origin=Adelaide,SA&destination=Adelaide,SA&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA&sensor=false

Inspection of the calculated route will indicate that the route is calculated using the following waypoint order:

"waypoint_order": [ 1, 0, 2, 3 ]

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. Currently two restrictions are supported:

• avoid=tolls
• avoid=highways

Note: the addition of restrictions does not preclude routes that include the restricted feature; it simply 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. (Note: origins expressed using coordinates rather than addresses always default to metric units.)

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:

• metric specifies usage of the metric system. Textual distances are returned using kilometers and meters.
• imperial specifies 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 also set the Directions service to return results biased to a particular region by use of the region parameter. This parameter takes a ccTLD (country code top-level domain) argument specifying the region bias. Most ccTLD codes are identical to ISO 3166-1 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").

You may utilize any domain in which the main Google Maps application has launched driving directions.

For example, a directions request from "Toldeo" to "Madrid" returns a result when region is set to es as "Toledo" is interpreted as the Spanish city:

http://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&sensor=false

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

A directions for "Toledo" to "Madrid" sent to with no region parameter will not return any results, since "Toledo" is interpreted as the city in Ohio:

http://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&sensor=false

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

Directions Responses

Directions responses are returned in the format indicated by the output flag within the URL request's path.

JSON Output

A sample HTTP request is shown below, calculating the route from Chicago, IL to Los Angeles, CA via two waypoints in Joplin, MO and Oklahoma City, OK:

http://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&sensor=false

The JSON result is shown below. Because directions results can be quite verbose, repeated elements within the response have been omitted for clarity.

{
  "status": "OK",
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}    

Generally, only one entry in the "routes" array is returned for directions lookups, though the Directions service may return several routes if you pass alternatives=true.

Note that these results generally need to be parsed if you wish to extract values from the results. Parsing JSON is relatively easy. See Parsing JSON for some recommended design patterns.

XML Output

In this example, the Directions API requests an xml response for the identical query shown above for :

http://maps.googleapis.com/maps/api/directions/xml?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&sensor=false

The XML returned by this request is shown below.

<DirectionsResponse> 
 <status>OK</status> 
 <route> 
  <summary>I-40 W</summary> 
  <leg> 
   <step> 
    <travel_mode>DRIVING</travel_mode> 
    <start_location> 
     <lat>41.8507300</lat> 
     <lng>-87.6512600</lng> 
    </start_location> 
    <end_location> 
     <lat>41.8525800</lat> 
     <lng>-87.6514100</lng> 
    </end_location> 
    <polyline> 
     <points>a~l~Fjk~uOwHJy@P</points> 
    </polyline> 
    <duration> 
     <value>19</value> 
     <text>1 min</text> 
    </duration> 
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions> 
    <distance> 
     <value>207</value> 
     <text>0.1 mi</text> 
    </distance> 
   </step> 
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration> 
    <value>74384</value> 
    <text>20 hours 40 mins</text> 
   </duration> 
   <distance> 
    <value>2137146</value> 
    <text>1,328 mi</text> 
   </distance> 
   <start_location> 
    <lat>35.4675602</lat> 
    <lng>-97.5164276</lng> 
   </start_location> 
   <end_location> 
    <lat>34.0522342</lat> 
    <lng>-118.2436849</lng> 
   </end_location> 
   <start_address>Oklahoma City, OK, USA</start_address> 
   <end_address>Los Angeles, CA, USA</end_address> 
  <copyrights>Map data ©2010 Google, Sanborn</copyrights> 
  <overview_polyline> 
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points> 
  </overview_polyline> 
  <optimized_waypoint_index>0</optimized_waypoint_index> 
  <optimized_waypoint_index>1</optimized_waypoint_index>
  <bounds> 
   <southwest> 
    <lat>34.0523600</lat> 
    <lng>-118.2435600</lng> 
   </southwest> 
   <northeast> 
    <lat>41.8781100</lat> 
    <lng>-87.6297900</lng> 
   </northeast> 
  </bounds>  
 </route> 
</DirectionsResponse>    

Note that the XML response consists of a single <DirectionsResponse> and two top-level elements:

• <status> contains metadata on the request. See Status Codes below.
• Zero or more <route> elements, each containing a single set of routing information between the origin and destination.

We recommend that you use json as the preferred output flag unless your service requires xml for some reason. Processing XML trees requires some care, so that you reference proper nodes and elements. See Parsing XML with XPath for some recommended design patterns for output processing.

The remainder of this documentation will use JSON syntax. In most cases, the output format does not matter for purposes of illustrating concepts or field names in the documentation. However, note the following subtle differences:

• XML results are wrapped in a root <DirectionsResponse> element.
• JSON denotes entries with multiple elements by plural arrays (steps), while XML denotes these using multiple singular elements (<step>).
• Blank elements are indicated through empty arrays in JSON, but by the absense of any such element in XML. A response that generates no results will return an empty routes array in JSON, but no <route> elements in XML, for example.

Directions Response Elements

Directions responses contain two root elements:

• "status" contains metadata on the request. See Status Codes below.
• "routes" contains an array of routes from the origin to the destination. See Routes below.

Routes consist of nested Legs and Steps.

Status Codes

The "status" field within the Directions response object contains the status of the request, and may contain debugging information to help you track down why the Directions service failed. The "status" field may contain the following values:

• OK indicates the response contains a valid result.
• NOT_FOUND indicates at least one of the locations specified in the requests's origin, destination, or waypoints could not be geocoded.
• ZERO_RESULTS indicates no route could be found between the origin and destination.
• MAX_WAYPOINTS_EXCEEDED indicates that too many waypointss were provided in the request The maximum allowed waypoints is 8, plus the origin, and destination. ( Google Maps API for Business customers may contain requests with up to 23 waypoints.)
• INVALID_REQUEST indicates that the provided request was invalid.
• OVER_QUERY_LIMIT indicates the service has received too many requests from your application within the allowed time period.
• REQUEST_DENIED indicates that the service denied use of the directions service by your application.
• UNKNOWN_ERROR indicates a directions request could not be processed due to a server error. The request may succeed if you try again.

Routes

When the Directions API returns results, it places them within a (JSON) routes array. Even if the service returns no results (such as if the origin and/or destination doesn't exist) it still returns an empty routes array. (XML responses consist of zero or more <route> elements.)

Each element of the routes array contains a single result from the specified origin and destination. This route may consist of one or more legs depending on whether any waypoints were specified. As well, the route also contains copyright and warning information which must be displayed to the user in addition to the routing information.

Each route within the routes field may contain the following fields:

• summary contains a short textual description for the route, suitable for naming and disambiguating the route from alternatives.
• legs[] contains an array which contains information about a leg of the route, between two locations within the given route. A separate leg will be present for each waypoint or destination specified. (A route with no waypoints will contain exactly one leg within the legs array.) Each leg consists of a series of steps. (See Directions Legs below.)
• waypoint_order contains an array indicating the order of any waypoints in the calculated route. This waypoints may be reordered if the request was passed optimize:true within its waypoints parameter.
• overview_polyline contains an object holding an array of encoded points that represent an approximate (smoothed) path of the resulting directions.
• bounds contains the viewport bounding box of this route.
• copyrights contains the copyrights text to be displayed for this route. You must handle and display this information yourself.
• warnings[] contains an array of warnings to be displayed when showing these directions. You must handle and display these warnings yourself.

Legs

Each element in the legs array specifies a single leg of the journey from the origin to the destination in the calculated route. For routes that contain no waypoints, the route will consist of a single "leg," but for routes that define one or more waypoints, the route will consist of one or more legs, corresponding to the specific legs of the journey.

Each leg within the legs field(s) may contain the following fields:

• steps[] contains an array of steps denoting information about each separate step of the leg of the journey. (See Directions Steps below.)

• distance indicates the total distance covered by this leg, as a field with the following elements:

  • value indicates the distance in meters
  • text contains a human-readable representation of the distance, displayed in units as used at the origin (or as overridden within the units parameter in the request). (For example, miles and feet will be used for any origin within the United States.) Note that regardless of what unit system is displayed as text, the distance.value field always contains a value expressed in meters.

  These fields may be absent if the distance is unknown.

• duration indicates the total duration of this leg, as a field with the following elements:

  • value indicates the duration in seconds.
  • text contains a human-readable representation of the duration.

  These fields may be absent if the duration is unknown.

• start_location contains the latitude/longitude coordinates of the origin of this leg. Because the Directions API calculates directions between locations by using the nearest transportation option (usually a road) at the start and end points, start_location may be different than the provided origin of this leg if, for example, a road is not near the origin.
• end_location contains the latitude/longitude coordinates of the given destination of this leg. Because the Directions API calculates directions between locations by using the nearest transportation option (usually a road) at the start and end points, end_location may be different than the provided destination of this leg if, for example, a road is not near the destination.
• start_address contains the human-readable address (typically a street address) reflecting the start_location of this leg.
• end_addresss contains the human-readable address (typically a street address) reflecting the end_location of this leg.

Steps

Each element in the steps array defines a single step of the calculated directions. A step is the most atomic unit of a direction's route, containing a single step describing a specific, single instruction on the journey. E.g. "Turn left at W. 4th St." The step not only describes the instruction but also contains distance and duration information relating to how this step relates to the following step. For example, a step denoted as "Merge onto I-80 West" may contain a duration of "37 miles" and "40 minutes," indicating that the next step is 37 miles/40 minutes from this step.

Each step within the steps field(s) may contain the following fields:

• html_instructions contains formatted instructions for this step, presented as an HTML text string.
• distance contains the distance covered by this step until the next step. (See the discussion of this field in Directions Legs above.) This field may be undefined if the distance is unknown.
• duration contains the typical time required to perform the step, until the next step (See the description in Directions Legs above.) This field may be undefined if the duration is unknown.
• start_location contains the location of the starting point of this step, as a single set of lat and lng fields.
• end_location contains the location of the starting point of this step, as a single set of lat and lng fields.