Developer's Guide

The Google Maps Directions API is a service that calculates directions between locations using an HTTP request.

This document is intended for website and mobile developers who want to 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.

Introduction

This video illustrates the use of the Google Maps Directions API to help people find their way. The video includes advice on proxying the web service via your server when you're using the API in a mobile app, to protect your API key.

With the Directions API, you can:

• Search for directions for several modes of transportation, including transit, driving, walking or cycling.
• Return multi-part directions using a series of waypoints.
• Specify origins, destinations, and waypoints as text strings (e.g. "Chicago, IL" or "Darwin, NT, Australia"), or as latitude/longitude coordinates, or as place IDs.

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.

Note: This service is not designed to respond in real time to user input. For dynamic directions calculations (for example, within a user interface element), consult the documentation for the Google Maps JavaScript API Directions Service.

Before you start developing with the Directions API, review the authentication requirements (you need an API key) and the API usage limits.

Directions Requests

A Google Maps Directions API request takes the following form:

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

where outputFormat may be either of the following values:

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

Note: URLs must be properly encoded to be valid and are limited to 2048 characters for all web services. Be aware of this limit when constructing your URLs.

HTTPS or HTTP

Security is important and HTTPS is recommended whenever possible, especially for applications that include sensitive user data, such as a user's location, in requests. Using HTTPS encryption makes your application more secure, and more resistant to snooping or tampering.

If HTTPS is not possible, to access the Google Maps Directions API over HTTP, use:

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

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.

Required parameters

• origin — The address, textual latitude/longitude value, or place ID from which you wish to calculate directions.
  • If you pass an address, the Directions service geocodes the string and converts it to a latitude/longitude coordinate to calculate directions. This coordinate may be different from that returned by the Google Maps Geocoding API, for example a building entrance rather than its center.

    origin=24+Sussex+Drive+Ottawa+ON

  • If you pass coordinates, they are used unchanged to calculate directions. Ensure that no space exists between the latitude and longitude values.

    origin=41.43206,-81.38992

  • Place IDs must be prefixed with place_id:. The place ID may only be specified if the request includes an API key or a Google Maps APIs Premium Plan client ID. You can retrieve place IDs from the Google Maps Geocoding API and the Google 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.

    origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

• destination — The address, textual latitude/longitude value, or place ID to which you wish to calculate directions. The options for the destination parameter are the same as for the origin parameter, described above.
• key — Your application's API key. This key identifies your application for purposes of quota management. Learn how to get a key.

  Note: Google Maps APIs Premium Plan customers may use either an API key, or a valid client ID and digital signature, in your Directions requests. Get more information on authentication parameters for Premium Plan customers.

Optional parameters

• mode (defaults to driving) — Specifies the mode of transport to use when calculating directions. Valid values and other request details are specified in Travel Modes.
• waypoints — Specifies an array of waypoints. Waypoints alter a route by routing it through the specified location(s). A waypoint is specified as a latitude/longitude coordinate, an encoded polyline, a place ID, or an address which will be geocoded. Encoded polylines must be prefixed with enc: and followed by a colon (:). Place IDs must be prefixed with place_id:. The place ID may only be specified if the request includes an API key or a Google Maps APIs Premium Plan client ID. Waypoints are only supported for driving, walking and bicycling directions. For more information on waypoints, see the guide to waypoints below.
• alternatives — 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 — Indicates that the calculated route(s) should avoid the indicated features. This parameter supports the following arguments:
  • tolls indicates that the calculated route should avoid toll roads/bridges.
  • highways indicates that the calculated route should avoid highways.
  • ferries indicates that the calculated route should avoid ferries.
  • indoor indicates that the calculated route should avoid indoor steps for walking and transit directions. Only requests that include an API key or a Google Maps APIs Premium Plan client ID will receive indoor steps by default.
  For more information see Route Restrictions below.
• language — Specifies the language in which to return results. See the list of supported domain languages. Note that we often update supported languages so this list may not be exhaustive. If language is not supplied, the service will attempt to use the native language of the domain from which the request is sent.
• units — Specifies the unit system to use when displaying results. Valid values are specified in Unit Systems below.
• region — Specifies the region code, specified as a ccTLD ("top-level domain") two-character value. (For more information see Region Biasing below.)
• arrival_time — Specifies the desired time of arrival for transit directions, in seconds since midnight, January 1, 1970 UTC. You can specify either departure_time or arrival_time, but not both. Note that arrival_time must be specified as an integer.
• departure_time — Specifies the desired time of departure. You can specify the time as an integer in seconds since midnight, January 1, 1970 UTC. Alternatively, you can specify a value of now, which sets the departure time to the current time (correct to the nearest second). The departure time may be specified in two cases:
  • For requests where the travel mode is transit: You can optionally specify one of departure_time or arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time).
  • For requests where the travel mode is driving: You can specify the departure_time to receive a route and trip duration (response field: duration_in_traffic) that take traffic conditions into account. This option is only available if the request contains a valid API key, or a valid Google Maps APIs Premium Plan client ID and signature. The departure_time must be set to the current time or some time in the future. It cannot be in the past.
• traffic_model (defaults to best_guess) — Specifies the assumptions to use when calculating time in traffic. This setting affects the value returned in the duration_in_traffic field in the response, which contains the predicted time in traffic based on historical averages. The traffic_model parameter may only be specified for driving directions where the request includes a departure_time, and only if the request includes an API key or a Google Maps APIs Premium Plan client ID. The available values for this parameter are:
  • best_guess (default) indicates that the returned duration_in_traffic should be the best estimate of travel time given what is known about both historical traffic conditions and live traffic. Live traffic becomes more important the closer the departure_time is to now.
  • pessimistic indicates that the returned duration_in_traffic should be longer than the actual travel time on most days, though occasional days with particularly bad traffic conditions may exceed this value.
  • optimistic indicates that the returned duration_in_traffic should be shorter than the actual travel time on most days, though occasional days with particularly good traffic conditions may be faster than this value.
  The default value of best_guess will give the most useful predictions for the vast majority of use cases. The best_guess travel time prediction may be shorter than optimistic, or alternatively, longer than pessimistic, due to the way the best_guess prediction model integrates live traffic information.
• transit_mode — Specifies one or more preferred modes of transit. This parameter may only be specified for transit directions, and only if the request includes an API key or a Google Maps APIs Premium Plan client ID. The parameter supports the following arguments:
  • bus indicates that the calculated route should prefer travel by bus.
  • subway indicates that the calculated route should prefer travel by subway.
  • train indicates that the calculated route should prefer travel by train.
  • tram indicates that the calculated route should prefer travel by tram and light rail.
  • rail indicates that the calculated route should prefer travel by train, tram, light rail, and subway. This is equivalent to transit_mode=train|tram|subway.
• transit_routing_preference — Specifies preferences for transit routes. Using this parameter, you can bias the options returned, rather than accepting the default best route chosen by the API. This parameter may only be specified for transit directions, and only if the request includes an API key or a Google Maps APIs Premium Plan client ID. The parameter supports the following arguments:
  • less_walking indicates that the calculated route should prefer limited amounts of walking.
  • fewer_transfers indicates that the calculated route should prefer a limited number of transfers.

Example Directions Requests

The following request returns driving directions from Toronto, Ontario to Montreal, Quebec.

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.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&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:

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

The following 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.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

The following request returns driving directions from Glasgow, UK to Perth, UK using place IDs.

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-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.
• walking requests walking directions via pedestrian paths & sidewalks (where available).
• bicycling requests bicycling directions via bicycle paths & preferred streets (where available).
• transit requests directions via public transit routes (where available). If you set the mode to transit, you can optionally specify either a departure_time or an arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time). You can also optionally include a transit_mode and/or a transit_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.

Waypoints

When calculating routes using the Google Maps Directions API, you may also specify waypoints for driving, walking or bicycling directions. Waypoints are not available for transit directions. You can use waypoints to calculate routes through additional locations, in which case the returned route includes stopovers at each of the given waypoints.

Specify the waypoints in the waypoints parameter.

• You can supply one or more locations separated by the pipe character (|), in the form of an address, latitude/longitude coordinates, or a place ID:
  • If you pass an address, the Directions service will geocode the string and convert it to a latitude/longitude coordinate to calculate directions. This coordinate may be different from that returned by the Google Maps Geocoding API, for example a building entrance rather than its center.
  • If you pass latitude/longitude coordinates, they will be used unchanged to calculate directions. Ensure that no space exists between the latitude and longitude values.
  • If you supply a place ID, you must prefix it with place_id:. You can only specify a place ID if the request includes an API key or a Google Maps APIs Premium Plan client ID. You can retrieve place IDs from the Google Maps Geocoding API and the Google 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.
• Alternatively, you can supply an encoded set of coordinates using the Encoded Polyline Algorithm. This is particularly useful if you have a large number of waypoints, because the URL is significantly shorter when using an encoded polyline.
  • 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 route between Boston, MA and Concord, MA with stopovers in Charlestown and Lexington, in that order:

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&key=YOUR_API_KEY

For each waypoint in the request, the directions response includes an additional entry in the legs array to provide the corresponding details for that leg of the journey.

If you'd like to influence the route using waypoints without adding a stopover, prefix the waypoint with via:. Waypoints prefixed with via: will not add an entry to the legs array, but will instead route the journey through the provided waypoint.

The following URL modifies the previous request such that the journey is routed through Lexington without stopping:

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|via:Lexington,MA&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 Google Maps Directions API.

The following URL requests waypoints using latitude/longitude coordinates:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:-37.81223%2C144.96254%7Cvia:-34.92788%2C138.60008&key=YOUR_API_KEY

Here is the same request, using an encoded polyline:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:enc:lexeF{~wsZejrPjtye@:&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 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.

https://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&key=YOUR_API_KEY

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. The following restrictions are supported:

• avoid=tolls
• avoid=highways
• avoid=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 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.

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 "Toledo" to "Madrid" returns a result when region is set to es as "Toledo" is interpreted as the Spanish city:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "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:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

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

Directions Responses

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

Sample Responses

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.

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

The above example requests JSON output. It's also possible to request XML output. Click the tabs below to see the sample JSON and XML responses.

Because directions results can be quite verbose, repeated elements within the responses have been omitted for clarity.

{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "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
      }
    }
  } ]
}

<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <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>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</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>

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 (such as steps and legs), while XML denotes these using multiple singular elements (such as <step> and <leg>).
• JSON denotes waypoint order via the waypoint_order field, while XML denotes these using individual <waypoint_index> elements.
• Blank elements are indicated through empty arrays in JSON, but by the absence 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 the following root elements:

• status contains metadata on the request. See Status Codes below.
• geocoded_waypoints contains an array with details about the geocoding of origin, destination and waypoints. See Geocoded Waypoints below.
• routes contains an array of routes from the origin to the destination. See Routes below. Routes consist of nested Legs and Steps.
• available_travel_modes contains an array of available travel modes. This field is returned when a request specifies a travel mode and gets no results. The array contains the available travel modes for the given set of waypoints that do have results. This field is not returned if one or more of the waypoints are via: waypoints. See details below.

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 request'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 waypoints were provided in the request. For applications using the Google Maps Directions API as a web service, the maximum allowed number of waypoints is 23, plus the origin and destination. If the request does not include an API key, the maximum allowed number of waypoints is 8. The maxiumum for the Directions service in the Google Maps JavaScript API is 8. Google Maps APIs Premium Plan customers may submit requests with up to 23 waypoints.
• INVALID_REQUEST indicates that the provided request was invalid. Common causes of this status include an invalid parameter or parameter value.
• 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.

Error Messages

When the status code is other than OK, there may be an additional error_message field within the Directions response object. This field contains more detailed information about the reasons behind the given status code.

Note: This field is not guaranteed to be always present, and its content is subject to change.

Geocoded Waypoints

Details about the geocoding of every waypoint, as well as origin and destination, can be found in the (JSON) geocoded_waypoints array. These can be used to infer why the service would return unexpected or no routes.

Elements in the geocoded_waypoints array correspond, by their zero-based position, to the origin, the waypoints in the order they are specified, and the destination. Each element includes the following details about the geocoding operation for the corresponding waypoint:

• geocoder_status indicates the status code resulting from the geocoding operation. This field may contain the following values.
  • "OK" indicates that no errors occurred; the address was successfully parsed and at least one geocode was returned.
  • "ZERO_RESULTS" indicates that the geocode was successful but returned no results. This may occur if the geocoder was passed a non-existent address.

• partial_match indicates that the geocoder did not return an exact match for the original request, though it was able to match part of the requested address. You may wish to examine the original request for misspellings and/or an incomplete address.

  Partial matches most often occur for street addresses that do not exist within the locality you pass in the request. Partial matches may also be returned when a request matches two or more locations in the same locality. For example, "21 Henr St, Bristol, UK" will return a partial match for both Henry Street and Henrietta Street. Note that if a request includes a misspelled address component, the geocoding service may suggest an alternative address. Suggestions triggered in this way will also be marked as a partial match.

• place_id is a unique identifier that can be used with other Google APIs. For example, you can use the place_id from a Google Place Autocomplete response to calculate directions to a local business. See the place ID overview.
• types indicates the address type of the geocoding result used for calculating directions. The following types are returned:
  • street_address indicates a precise street address.
  • route indicates a named route (such as "US 101").
  • intersection indicates a major intersection, usually of two major roads.
  • political indicates a political entity. Usually, this type indicates a polygon of some civil administration.
  • country indicates the national political entity, and is typically the highest order type returned by the Geocoder.
  • administrative_area_level_1 indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels.
  • administrative_area_level_2 indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.
  • administrative_area_level_3 indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  • administrative_area_level_4 indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  • administrative_area_level_5 indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  • colloquial_area indicates a commonly-used alternative name for the entity.
  • locality indicates an incorporated city or town political entity.
  • ward indicates a specific type of Japanese locality, to facilitate distinction between multiple locality components within a Japanese address.
  • sublocality indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: sublocality_level_1 to sublocality_level_5. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area.
  • neighborhood indicates a named neighborhood
  • premise indicates a named location, usually a building or collection of buildings with a common name
  • subpremise indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name
  • postal_code indicates a postal code as used to address postal mail within the country.
  • natural_feature indicates a prominent natural feature.
  • airport indicates an airport.
  • park indicates a named park.
  • point_of_interest indicates a named point of interest. Typically, these "POI"s are prominent local entities that don't easily fit in another category, such as "Empire State Building" or "Statue of Liberty."

  An empty list of types indicates there are no known types for the particular address component, for instance Lieu-dit in France.

These details will not be present for waypoints specified as textual latitude/longitude values if the service returns no results. This is because such waypoints are only reverse geocoded to obtain their representative address after a route has been found. An empty JSON object will occupy the corresponding places in the geocoded_waypoints array.

Routes

When the Google Maps 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 (or <waypoint_index> in XML) 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 a single points object that holds an encoded polyline representation of the route. This polyline is an approximate (smoothed) path of the resulting directions.
• bounds contains the viewport bounding box of the overview_polyline.
• 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.
• fare: If present, contains the total fare (that is, the total ticket costs) on this route. This property is only returned for transit requests and only for routes where fare information is available for all transit legs. The information includes:
  • currency: An ISO 4217 currency code indicating the currency that the amount is expressed in.
  • value: The total fare amount, in the currency specified above.
  • text: The total fare amount, formatted in the requested language.

Below is an example of fare information within a route:

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

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.

• duration_in_traffic indicates the total duration of this leg. This value is an estimate of the time in traffic based on current and historical traffic conditions. See the traffic_model request parameter for the options you can use to request that the returned value is optimistic, pessimistic, or a best-guess estimate. The duration in traffic is returned only if all of the following are true:

  • The request includes a valid API key, or a valid Google Maps APIs Premium Plan client ID and signature.
  • The request does not include stopover waypoints. If the request includes waypoints, they must be prefixed with via: to avoid stopovers.
  • The request is specifically for driving directions—the mode parameter is set to driving.
  • The request includes a departure_time parameter.
  • Traffic conditions are available for the requested route.

  The duration_in_traffic contains the following fields:

  • value indicates the duration in seconds.
  • text contains a human-readable representation of the duration.
• arrival_time contains the estimated time of arrival for this leg. This property is only returned for transit directions. The result is returned as a Time object with three properties:
  • value the time specified as a JavaScript Date object.
  • text the time specified as a string. The time is displayed in the time zone of the transit stop.
  • time_zone contains the time zone of this station. The value is the name of the time zone as defined in the IANA Time Zone Database, e.g. "America/New_York".
• departure_time contains the estimated time of departure for this leg, specified as a Time object. The departure_time is only available for transit directions.
• 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 Google Maps 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) resulting from reverse geocoding the start_location of this leg.
• end_address contains the human-readable address (typically a street address) from reverse geocoding 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.

When using the Google Maps Directions API to search for transit directions, the steps array will include additional transit details in the form of a transit_details array. If the directions include multiple modes of transportation, detailed directions will be provided for walking or driving steps in an inner steps array. For example, a walking step will include directions from the start and end locations: "Walk to Innes Ave & Fitch St". That step will include detailed walking directions for that route in the inner steps array, such as: "Head north-west", "Turn left onto Arelious Walker", and "Turn left onto Innes Ave".

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 last point of this step, as a single set of lat and lng fields.
• polyline contains a single points object that holds an encoded polyline representation of the step. This polyline is an approximate (smoothed) path of the step.
• steps contains detailed directions for walking or driving steps in transit directions. Substeps are only available when travel_mode is set to "transit". The inner steps array is of the same type as steps.
• transit_details contains transit specific information. This field is only returned with travel_mode is set to "transit". See Transit Details below.

Transit Details

Transit directions return additional information that is not relevant for other modes of transportation. These additional properties are exposed through the transit_details object, returned as a field of an element in the steps[] array. From the TransitDetails object you can access additional information about the transit stop, transit line and transit agency.

A transit_details object may contain the following fields:

• arrival_stop and departure_stop contains information about the stop/station for this part of the trip. Stop details can include:
  • name the name of the transit station/stop. eg. "Union Square".
  • location the location of the transit station/stop, represented as a lat and lng field.
• arrival_time and departure_time contain the arrival or departure times for this leg of the journey, specified as the following three properties:
  • text the time specified as a string. The time is displayed in the time zone of the transit stop.
  • value the time specified as Unix time, or seconds since midnight, January 1, 1970 UTC.
  • time_zone contains the time zone of this station. The value is the name of the time zone as defined in the IANA Time Zone Database, e.g. "America/New_York".
• headsign specifies the direction in which to travel on this line, as it is marked on the vehicle or at the departure stop. This will often be the terminus station.
• headway specifies the expected number of seconds between departures from the same stop at this time. For example, with a headway value of 600, you would expect a ten minute wait if you should miss your bus.
• num_stops contains the number of stops in this step, counting the arrival stop, but not the departure stop. For example, if your directions involve leaving from Stop A, passing through stops B and C, and arriving at stop D, num_stops will return 3.
• line contains information about the transit line used in this step, and may include the the following properties:
  • name contains the full name of this transit line. eg. "7 Avenue Express".
  • short_name contains the short name of this transit line. This will normally be a line number, such as "M7" or "355".
  • color contains the color commonly used in signage for this transit line. The color will be specified as a hex string such as: #FF0033.
  • agencies contains an array of TransitAgency objects that each provide information about the operator of the line, including the following properties:
    • name contains the name of the transit agency.
    • url contains the URL for the transit agency.
    • phone contains the phone number of the transit agency.

    You must display the names and URLs of the transit agencies servicing the trip results.

  • url contains the URL for this transit line as provided by the transit agency.
  • icon contains the URL for the icon associated with this line.
  • text_color contains the color of text commonly used for signage of this line. The color will be specified as a hex string.
  • vehicle contains the type of vehicle used on this line. This may include the following properties:
    • name contains the name of the vehicle on this line. eg. "Subway."
    • type contains the type of vehicle that runs on this line. See the Vehicle Type documentation for a complete list of supported values.
    • icon contains the URL for an icon associated with this vehicle type.
    • local_icon contains the URL for the icon associated with this vehicle type, based on the local transport signage.

Vehicle Type

The vehicle.type property may return any of the following values:

Available Travel Modes

The response field available_travel_modes contains an array of available travel modes. This field is returned when a request specifies a travel mode and gets no results. The array contains the available travel modes for the given set of waypoints that do have results. The field is not returned if any of the waypoints are via: waypoints.

For example, try this request:

http://maps.googleapis.com/maps/api/directions/json?&mode=transit&origin=frontera+el+hierro&destination=la+restinga+el+hierro&departure_time=1399995076&key=YOUR_API_KEY

It produces this response:

{
   "available_travel_modes" : [ "DRIVING", "BICYCLING", "WALKING" ],
   "geocoded_waypoints" : [
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJwZNMti1fawwRO2aVVVX2yKg",
         "types" : [ "locality", "political" ]
      },
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJ3aPgQGtXawwRLYeiBMUi7bM",
         "types" : [ "locality", "political" ]
      }
   ],
   "routes" : [],
   "status" : "ZERO_RESULTS"
}

The sensor Parameter

The Google Maps API previously required that you include the sensor parameter to indicate whether your application used a sensor to determine the user's location. This parameter is no longer required.