The Google Geocoding API

What is Geocoding?

Geocoding is the process of converting addresses (like "1600 Amphitheatre Parkway, Mountain View, CA") into geographic coordinates (like latitude 37.423021 and longitude -122.083739), which you can use to place markers or position the map. The Google Geocoding API provides a direct way to access a geocoder via an HTTP request. Additionally, the service allows you to perform the converse operation (turning coordinates into addresses); this process is known as "reverse geocoding."

Audience

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

This service is generally designed for geocoding 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 geocoding (for example, within a user interface element), consult the documentation for the JavaScript API V2 Client Geocoder, the JavaScript API V3 Client Geocoder, or the Maps API for Flash Client Geocoder.

Geocoding is a time and resource intensive task. Whenever possible, pre-geocode known addresses (using the Geocoding API described here or another geocoding service), and store your results in a temporary cache of your own design.

Usage Limits

Use of the Google Geocoding API is subject to a query limit of 2,500 geolocation requests per day. (User of Google Maps API for Business may perform up to 100,000 requests per day.) This limit is enforced to prevent abuse and/or repurposing of the Geocoding API, and this limit may be changed in the future without notice. Additionally, we enforce a request rate limit to prevent abuse of the service. If you exceed the 24-hour limit or otherwise abuse the service, the Geocoding API may stop working for you temporarily. If you continue to exceed this limit, your access to the Geocoding API may be blocked.

Note: the Geocoding API may only be used in conjunction with a Google map; geocoding results without displaying them on a map is prohibited. For complete details on allowed usage, consult the Maps API Terms of Service License Restrictions.

Geocoding Requests

A Geocoding API request must be of the following form:

http://maps.googleapis.com/maps/api/geocode/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 Geocoding API over HTTPS, use:

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

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

In either case, certain parameters are required while some 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 Geocoding API defines a geocoding request using the following URL parameters:

• address (required) — The address that you want to geocode.*

     OR

• latlng (required) — The textual latitude/longitude value for which you wish to obtain the closest, human-readable address.*
• bounds (optional) — The bounding box of the viewport within which to bias geocode results more prominently. (For more information see Viewport Biasing below.)
• region (optional) — The region code, specified as a ccTLD ("top-level domain") two-character value. (For more information see Region Biasing below.)
• language (optional) — The language in which to return results. See the supported list of domain languages. Note that we often update supported languages so this list may not be exhaustive. If language is not supplied, the geocoder will attempt to use the native language of the domain from which the request is sent wherever possible.
• sensor (required) — Indicates whether or not the geocoding 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 latlng to lookup. (If you pass a latlng, the geocoder performs what is known as a reverse geocode. See Reverse Geocoding for more information.)

The bounds and region parameters will only influence, not fully restrict, results from the geocoder.

Geocoding Responses

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

JSON Output Formats

In this example, the Geocoding API requests a json response for a query on "1600 Amphitheatre Parkway, Mountain View, CA":

http://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false

We've left the sensor parameter in this example as a variable true_or_false to emphasize that you must set this value to either true or false explicitly.

The JSON returned by this request is shown below. Note that actual JSON may contain less whitespace. You should not make assumptions about the amount or format of whitespace between requests.

{
  "status": "OK",
  "results": [ {
    "types": [ "street_address" ],
    "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    "address_components": [ {
      "long_name": "1600",
      "short_name": "1600",
      "types": [ "street_number" ]
    }, {
      "long_name": "Amphitheatre Pkwy",
      "short_name": "Amphitheatre Pkwy",
      "types": [ "route" ]
    }, {
      "long_name": "Mountain View",
      "short_name": "Mountain View",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "California",
      "short_name": "CA",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    }, {
      "long_name": "94043",
      "short_name": "94043",
      "types": [ "postal_code" ]
    } ],
    "geometry": {
      "location": {
        "lat": 37.4219720,
        "lng": -122.0841430
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "southwest": {
          "lat": 37.4188244,
          "lng": -122.0872906
        },
        "northeast": {
          "lat": 37.4251196,
          "lng": -122.0809954
        }
      }
    }
  } ]
}

Note that the JSON response contains two root elements:

• "status" contains metadata on the request. See Status Codes below.
• "results" contains an array of geocoded address information and geometry information.

Generally, only one entry in the "results" array is returned for address lookups, though the geocoder may return several results when address queries are ambiguous.

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 Formats

In this example, the Geocoding API requests an xml response for the identical query shown above for "1600 Amphitheatre Parkway, Mountain View, CA":

http://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false

The XML returned by this request is shown below.

<GeocodeResponse> 
 <status>OK</status> 
 <result> 
  <type>street_address</type> 
  <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> 
  <address_component> 
   <long_name>1600</long_name> 
   <short_name>1600</short_name> 
   <type>street_number</type> 
  </address_component> 
  <address_component> 
   <long_name>Amphitheatre Pkwy</long_name> 
   <short_name>Amphitheatre Pkwy</short_name> 
   <type>route</type> 
  </address_component> 
  <address_component> 
   <long_name>Mountain View</long_name> 
   <short_name>Mountain View</short_name> 
   <type>locality</type> 
   <type>political</type> 
  </address_component> 
  <address_component> 
   <long_name>San Jose</long_name> 
   <short_name>San Jose</short_name> 
   <type>administrative_area_level_3</type> 
   <type>political</type> 
  </address_component> 
  <address_component> 
   <long_name>Santa Clara</long_name> 
   <short_name>Santa Clara</short_name> 
   <type>administrative_area_level_2</type> 
   <type>political</type> 
  </address_component> 
  <address_component> 
   <long_name>California</long_name> 
   <short_name>CA</short_name> 
   <type>administrative_area_level_1</type> 
   <type>political</type> 
  </address_component> 
  <address_component> 
   <long_name>United States</long_name> 
   <short_name>US</short_name> 
   <type>country</type> 
   <type>political</type> 
  </address_component> 
  <address_component> 
   <long_name>94043</long_name> 
   <short_name>94043</short_name> 
   <type>postal_code</type> 
  </address_component> 
  <geometry> 
   <location> 
    <lat>37.4217550</lat> 
    <lng>-122.0846330</lng> 
   </location> 
   <location_type>ROOFTOP</location_type> 
   <viewport> 
    <southwest> 
     <lat>37.4188514</lat> 
     <lng>-122.0874526</lng> 
    </southwest> 
    <northeast> 
     <lat>37.4251466</lat> 
     <lng>-122.0811574</lng> 
    </northeast> 
   </viewport> 
  </geometry> 
 </result> 
</GeocodeResponse> 

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

• <status> contains metadata on the request. See Status Codes below.
• Zero or more <result> elements, each containing a single set of geocoded address information and geometry information.

Note that this response is considerably longer than the JSON response. For that reason, we recommend that you use json as the preferred output flag unless your service requires xml for some reason. Additionally, 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 <GeocodeResponse> element.
• JSON denotes entries with multiple elements by plural arrays (types), while XML denotes these using multiple singular elements (<type>).
• 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 results array in JSON, but no <result> elements in XML, for example.

Status Codes

The "status" field within the Geocoding response object contains the status of the request, and may contain debugging information to help you track down why Geocoding is not working. The "status" 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 geocode was passed a non-existent address or a latlng in a remote location.
• "OVER_QUERY_LIMIT" indicates that you are over your quota.
• "REQUEST_DENIED" indicates that your request was denied, generally because of lack of a sensor parameter.
• "INVALID_REQUEST" generally indicates that the query (address or latlng) is missing.

Results

When the geocoder returns results, it places them within a (JSON) results array. Even if the geocoder returns no results (such as if the address doesn't exist) it still returns an empty results array. (XML responses consist of zero or more <result> elements.)

A typical result is made up of the following fields:

• The types[] array indicates the type of the returned result. This array contains a set of one or more tags identifying the type of feature returned in the result. For example, a geocode of "Chicago" returns "locality" which indicates that "Chicago" is a city, and also returns "political" which indicates it is a political entity.

• formatted_address is a string containing the human-readable address of this location. Often this address is equivalent to the "postal address," which sometimes differs from country to country. (Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions.) This address is generally composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" contains separate address components for "111" (the street number, "8th Avenue" (the route), "New York" (the city) and "NY" (the US state). These address components contain additional information as noted below.

• address_components[] is an array containing the separate address components, as explained above. Each address_component typically contains:

  • types[] is an array indicating the type of the address component.
  • long_name is the full text description or name of the address component as returned by the Geocoder.
  • short_name is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska may have a long_name of "Alaska" and a short_name of "AK" using the 2-letter postal abbreviation.

  Note that address_components[] may contain more address components than noted within the formatted_address.

• geometry contains the following information:

  • location contains the geocoded latitude,longitude value. For normal address lookups, this field is typically the most important.

  • location_type stores additional data about the specified location. The following values are currently supported:

    • "ROOFTOP" indicates that the returned result is a precise geocode for which we have location information accurate down to street address precision.
    • "RANGE_INTERPOLATED" indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address.
    • "GEOMETRIC_CENTER" indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
    • "APPROXIMATE" indicates that the returned result is approximate.
  • viewport contains the recommended viewport for displaying the returned result, specified as two latitude,longitude values defining the southwest and northeast corner of the viewport bounding box. Generally the viewport is used to frame a result when displaying it to a user.
  • bounds (optionally returned) stores the bounding box which can fully contain the returned result. Note that these bounds may not match the recommended viewport. (For example, San Francisco includes the Farallon islands, which are technically part of the city, but probably should not be returned in the viewport.)
• partial_match indicates that the geocoder did not return an exact match for the original request, though it did 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.

As the exact format of an individual response to a Geocoding API request is not guaranteed, you should never assume that elements are in absolute positions. (In particular, the number of address_components within a Geocoding API response vary based on the address requested and can change over time.) Instead, you should parse the response and select appropriate values via expressions. See Parsing Web Service Responses for more information.

Address Component Types

The types[] array within the returned result indicates the address type. These types may also be returned within address_components[] arrays to indicate the type of the particular address component. Addresses within the geocoder may have multiple types; the types may be considered "tags". For example, many cities are tagged with the political and locality type.

The following types are supported and returned by the HTTP Geocoder:

• 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.
• colloquial_area indicates a commonly-used alternative name for the entity.
• locality indicates an incorporated city or town political entity.
• sublocality indicates an first-order civil entity below a locality
• 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."

In addition to the above, address components may exhibit the following types:

• post_box indicates a specific postal box.
• street_number indicates the precise street number.
• floor indicates the floor of a building address.
• room indicates the room of a building address.

Reverse Geocoding (Address Lookup)

The term geocoding generally refers to translating a human-readable address into a location on a map. The process of doing the converse, translating a location on the map into a human-readable address, is known as reverse geocoding.

The Geocoding API supports reverse geocoding directly using the latlng parameter. For example, the following query contains the latitude/longitude value for a location in Brooklyn:

http://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&sensor=true_or_false

Note: Ensure that no space exists between the latitude and longitude values when passed in the latlng parameter.

This query returns the following result:

{
  "status": "OK",
  "results": [ {
    "types": [ "street_address" ],
    "formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
    "address_components": [ {
      "long_name": "275-291",
      "short_name": "275-291",
      "types": [ "street_number" ]
    }, {
      "long_name": "Bedford Ave",
      "short_name": "Bedford Ave",
      "types": [ "route" ]
    }, {
      "long_name": "New York",
      "short_name": "New York",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Brooklyn",
      "short_name": "Brooklyn",
      "types": [ "administrative_area_level_3", "political" ]
    }, {
      "long_name": "Kings",
      "short_name": "Kings",
      "types": [ "administrative_area_level_2", "political" ]
    }, {
      "long_name": "New York",
      "short_name": "NY",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    }, {
      "long_name": "11211",
      "short_name": "11211",
      "types": [ "postal_code" ]
    } ],
    "geometry": {
      "location": {
        "lat": 40.7142298,
        "lng": -73.9614669
      },
      "location_type": "RANGE_INTERPOLATED",
      "viewport": {
        "southwest": {
          "lat": 40.7110822,
          "lng": -73.9646145
        },
        "northeast": {
          "lat": 40.7173774,
          "lng": -73.9583193
        }
      }
    }
  },
  
  ... Additional results[] ...

Note that the reverse geocoder returned more than one result. The result's "formatted_addresses" are not just postal addresses, but any way to geographically name a location. For example, when geocoding a point in the city of Chicago, the geocoded point may be denoted as a street address, as the city (Chicago), as its state (Illinois) or as a country (The United States). All are "addresses" to the geocoder. The reverse geocoder returns any of these types as valid results.

The reverse geocoder matches political entities (countries, provinces, cities and neighborhoods), street addresses, and postal codes.

The full list of formatted_address values returned by the previous query are shown below.

"formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
"formatted_address": "Williamsburg, NY, USA",
"formatted_address": "New York 11211, USA",
"formatted_address": "Kings, New York, USA",
"formatted_address": "Brooklyn, NY, USA",
"formatted_address": "New York, NY, USA",
"formatted_address": "New York, USA",
"formatted_address": "United States"

Generally, addresses are returned from most specific to least specific; the more exact address is the most prominent result, as it is in this case. Note that we return different types of addresses, from the most specific street address to less specific political entities such as neighborhoods, cities, counties, states, etc. If you wish to match a more general address, you may wish to inspect the "types" field of the returned Placemarks. (See Address Component Types above.)

Note: Reverse geocoding is an estimate. The geocoder will attempt to find the closest addressable location within a certain tolerance; if no match is found, the geocoder will return zero results.

Viewport Biasing

You can also instruct the Geocoding service to prefer results within a given viewport (expressed as a bounding box). You do so within the request URL by setting the bounds parameter. Note that biasing only prefers results within the bounds; if more relevant results exist outside of these bounds, they may be included.

The bounds parameter defines the latitude/longitude coordinates of the southwest and northeast corners of this bounding box using a pipe (|) character to separate the coordinates.

For example, a geocode for "Winnetka" generally returns this suburb of Chicago:

Request:

http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&sensor=false

Response:

{
  "status": "OK",
  "results": [ {
    "types": [ "locality", "political" ],
    "formatted_address": "Winnetka, IL, USA",
    "address_components": [ {
      "long_name": "Winnetka",
      "short_name": "Winnetka",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Illinois",
      "short_name": "IL",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    } ],
    "geometry": {
      "location": {
        "lat": 42.1083080,
        "lng": -87.7417070
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 42.0917501,
          "lng": -87.7737218
        },
        "northeast": {
          "lat": 42.1248616,
          "lng": -87.7096922
        }
      },
      "bounds": {
        "southwest": {
          "lat": 42.0885320,
          "lng": -87.7715480
        },
        "northeast": {
          "lat": 42.1284090,
          "lng": -87.7110160
        }
      }
    }
  } ]
}

However, adding a bounds argument defining a bounding box for the San Fernando Valley of Los Angeles results in this geocode returning the neighborhood named "Winnetka" in that location:

Request:

http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&sensor=false

Response:

{
  "status": "OK",
  "results": [ {
    "types": [ "sublocality", "political" ],
    "formatted_address": "Winnetka, California, USA",
    "address_components": [ {
      "long_name": "Winnetka",
      "short_name": "Winnetka",
      "types": [ "sublocality", "political" ]
    }, {
      "long_name": "Los Angeles",
      "short_name": "Los Angeles",
      "types": [ "administrative_area_level_3", "political" ]
    }, {
      "long_name": "Los Angeles",
      "short_name": "Los Angeles",
      "types": [ "administrative_area_level_2", "political" ]
    }, {
      "long_name": "California",
      "short_name": "CA",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    } ],
    "geometry": {
      "location": {
        "lat": 34.2131710,
        "lng": -118.5710220
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 34.1947148,
          "lng": -118.6030368
        },
        "northeast": {
          "lat": 34.2316232,
          "lng": -118.5390072
        }
      },
      "bounds": {
        "southwest": {
          "lat": 34.1791050,
          "lng": -118.5883200
        },
        "northeast": {
          "lat": 34.2353090,
          "lng": -118.5534191
        }
      }
    }
  } ]
}

Region Biasing

The Google Geocoding API returns address results influenced by the region (typically the country) from which the request is sent. For example, searches for "San Francisco" may return different results if sent from a domain within the United States than one sent from Spain.

You can set the Geocoding API to return results biased to a particular region using 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").

Geocoding results can be biased for every domain in which the main Google Maps application is officially launched. Note that biasing only prefers results for a specific domain; if more relevant results exist outside of this domain, they may be included.

For example, a geocode for "Toledo" returns this result, as the default domain for the Geocoding API is set to the United States:

http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false
# Returns:
#
{
  "status": "OK",
  "results": [ {
    "types": [ "locality", "political" ],
    "formatted_address": "Toledo, OH, USA",
    "address_components": [ {
      "long_name": "Toledo",
      "short_name": "Toledo",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Ohio",
      "short_name": "OH",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "United States",
      "short_name": "US",
      "types": [ "country", "political" ]
    } ],
    "geometry": {
      "location": {
        "lat": 41.6529200,
        "lng": -83.5777820
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 41.5861889,
          "lng": -83.7058414
        },
        "northeast": {
          "lat": 41.7195821,
          "lng": -83.4497226
        }
      },
      "bounds": {
        "southwest": {
          "lat": 41.5803170,
          "lng": -83.6947540
        },
        "northeast": {
          "lat": 41.7326310,
          "lng": -83.4545660
        }
      }
    }
  } ]
}

A geocode for "Toledo" with region=es (Spain) will return the Spanish city:

http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false&region=es
#
# Returns
#
{
  "status": "OK",
  "results": [ {
    "types": [ "locality", "political" ],
    "formatted_address": "Toledo, España",
    "address_components": [ {
      "long_name": "Toledo",
      "short_name": "Toledo",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Toledo",
      "short_name": "TO",
      "types": [ "administrative_area_level_2", "political" ]
    }, {
      "long_name": "Castilla-La Mancha",
      "short_name": "CM",
      "types": [ "administrative_area_level_1", "political" ]
    }, {
      "long_name": "España",
      "short_name": "ES",
      "types": [ "country", "political" ]
    } ],
    "geometry": {
      "location": {
        "lat": 39.8567775,
        "lng": -4.0244759
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 39.7882200,
          "lng": -4.1525353
        },
        "northeast": {
          "lat": 39.9252666,
          "lng": -3.8964165
        }
      },
      "bounds": {
        "southwest": {
          "lat": 39.8105550,
          "lng": -4.1796354
        },
        "northeast": {
          "lat": 39.9250920,
          "lng": -3.8147915
        }
      }
    }
  } ]
}