Developer's Guide

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 on a map, or position the map.

Reverse geocoding is the process of converting geographic coordinates into a human-readable address. The Google Maps Geocoding API's reverse geocoding service also lets you find the address for a given place ID.

The Google Maps Geocoding API provides a direct way to access these services via an HTTP request. The following example uses the Geocoding service through the Google Maps JavaScript API to demonstrate the basic functionality.

View this example full screen to see additional functionality of the Geocoding API, such as more options available for tailoring the request (component filtering and viewport biasing) and more details about each result.

Before You Begin

This document describes the Google Maps Geocoding API web service. It is intended for website and mobile developers who want to use geocoding data within maps provided by one of the Google Maps APIs.

Note: 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 dynamic geocoding (for example, within a user interface element), consult the documentation for the Google Maps JavaScript API client geocoder and/or the Google Play services Location APIs.

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

To use the Google Maps Geocoding API, you need an API key. Before you start developing with the Geocoding API, review the authentication requirements and the API usage limits.

Google Maps Geocoding API Request Format

A Google Maps Geocoding API request takes the following form:

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

where outputFormat may be either of the following values:

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

To access the Google Maps Geocoding API over HTTP, use:

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

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.

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. Note that different browsers, proxies, and servers may have different URL character limits as well.

Some parameters are required while some are optional. As is standard in URLs, parameters are separated using the ampersand (&) character.

The rest of this page describes geocoding and reverse geocoding separately, because different parameters are available for each type of request.

Geocoding (Latitude/Longitude Lookup)

Required parameters in a geocoding request:

• address — The street address that you want to geocode, in the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. Please refer to the FAQ for additional guidance.
       or
  components — A component filter for which you wish to obtain a geocode. See Component Filtering for more information. The components filter will also be accepted as an optional parameter if an address is provided.
• 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 Geocoding requests. Get more information on authentication parameters for Premium Plan customers.

Optional parameters in a geocoding request:

• bounds — The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. (For more information see Viewport Biasing below.)
• language — 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 geocoder will attempt to use the preferred language as specified in the Accept-Language header, or the native language of the domain from which the request is sent. The geocoder will do its best to provide a street address that is readable for both the user and locals. To achieve that goal, it will return street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses will be returned in the preferred language. Address components will all be returned in the same language, which is chosen from the first component. Should names not be available in the preferred language, the closest match will be used.
• region — The region code, specified as a ccTLD ("top-level domain") two-character value. This parameter will only influence, not fully restrict, results from the geocoder. (For more information see Region Biasing below.)
• components — The component filters, separated by a pipe (|). Each component filter consists of a component:value pair and will fully restrict the results from the geocoder. For more information see Component Filtering, below.

Geocoding Responses

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

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

This request demonstrates using the JSON output flag:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

This request demonstrates using the XML output flag:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Click the tabs below to see the sample JSON and XML responses.

{
   "results" : [
      {
         "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" : "Santa Clara County",
               "short_name" : "Santa Clara County",
               "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" ]
            },
            {
               "long_name" : "94043",
               "short_name" : "94043",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

<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>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

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 geocoder was passed a non-existent address.
• "OVER_QUERY_LIMIT" indicates that you are over your quota.
• "REQUEST_DENIED" indicates that your request was denied.
• "INVALID_REQUEST" generally indicates that the query (address, components or latlng) is missing.
• "UNKNOWN_ERROR" indicates that the request could not be processed due to a server error. The request may succeed if you try again.

Error Messages

When the geocoder returns a status code other than OK, there may be an additional error_message field within the Geocoding 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.

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 zero 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.

• postcode_localities[] is an array denoting all the localities contained in a postal code. This is only present when the result is a postal code that contains multiple localities.

• 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 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 in a Google Places API request to get details of a local business, such as phone number, opening hours, user reviews, and more. See the place ID overview.

As the exact format of an individual response to a Google Maps 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 Types and Address Component Types

The types[] array in the result indicates the address type. Examples of address types include a street address, a country, or a political entity. There is also a types[] array in the address_components[], indicating the type of each part of the address. Examples include street number or country. (Below is a full list of types.) Addresses may have multiple types. The types may be considered 'tags'. For example, many cities are tagged with the political and the locality type.

The following types are supported and returned by the geocoder in both the address type and address component type arrays:

• 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.

In addition to the above, address components may include the types below.

Note: This list is not exhaustive, and is subject to change.

• floor indicates the floor of a building address.
• establishment typically indicates a place that has not yet been categorized.
• point_of_interest indicates a named point of interest.
• parking indicates a parking lot or parking structure.
• post_box indicates a specific postal box.
• postal_town indicates a grouping of geographic areas, such as locality and sublocality, used for mailing addresses in some countries.
• room indicates the room of a building address.
• street_number indicates the precise street number.
• bus_station, train_station and transit_station indicate the location of a bus, train or public transit stop.

Viewport Biasing

In a geocoding request, you can 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:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

Response:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

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:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

Response:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles County",
               "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" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

Region Biasing

In a geocoding response, the Google Maps 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 Google Maps 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 Google Maps Geocoding API is set to the United States. Request:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Response:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

A geocoding request for "Toledo" with region=es (Spain) will return the Spanish city. Request:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Response:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Component Filtering

In a geocoding response, the Google Maps Geocoding API can return address results restricted to a specific area. The restriction is specified using the components filter. A filter consists of a list of component:value pairs separated by a pipe (|). Only the results that match all the filters will be returned. Filter values support the same methods of spelling correction and partial matching as other geocoding requests. If a geocoding result is a partial match for a component filter it will contain a partial_match field in the response.

The components that can be filtered include:

• route matches long or short name of a route.
  
• locality matches against both locality and sublocality types.
• administrative_area matches all the administrative_area levels.
• postal_code matches postal_code and postal_code_prefix.
• country matches a country name or a two letter ISO 3166-1 country code.

Note: Each address component can only be specified either in the address parameter or as a component filter, but not both. Doing so may result in ZERO_RESULTS.

A geocode for "Santa Cruz" with components=country:ES will return Santa Cruz de Tenerife in Canary Islands, Spain. Request:

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&key=YOUR_API_KEY

Response:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

A query containing a component filter will only return the geocoding results that match the filter. If no matches are found, the geocoder will return a result that matches the filter itself. Request:

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

Response:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Component filtering will return a ZERO_RESULTS response only if you provide filters that exclude each other. Request:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Response:

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

Using the components filter it is possible to make a query without the address parameter, but you cannot specify a component without a value. Request:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Response:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

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 opposite, translating a location on the map into a human-readable address, is known as reverse geocoding.

Required parameters in a reverse geocoding request:

• latlng — The latitude and longitude values specifying the location for which you wish to obtain the closest, human-readable address.
       or
  place_id — The place ID of the place for which you wish to obtain the human-readable address. The place ID is a unique identifier that can be used with other Google APIs. For example, you can use the placeID returned by the Google Maps Roads API to get the address for a snapped point. For more information about place IDs, see the place ID overview. The place ID may only be specified if the request includes an API key or a Google Maps APIs Premium Plan client ID.
• 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 reverse Geocoding requests. Get more information on authentication parameters for Premium Plan customers.

Optional parameters in a reverse geocoding request:

These are the optional parameters that you can include in a reverse geocoding request:

• language — 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 geocoder will attempt to use the native language of the domain from which the request is sent wherever possible.
• result_type — One or more address types, separated by a pipe (|). Examples of address types: country, street_address, postal_code. For a full list of allowable values, see the address types on this page. Specifying a type will restrict the results to this type. If multiple types are specified, the API will return all addresses that match any of the types. Note: This parameter is available only for requests that include an API key or a client ID.
• location_type — One or more location types, separated by a pipe (|). Specifying a type will restrict the results to this type. If multiple types are specified, the API will return all addresses that match any of the types. Note: This parameter is available only for requests that include an API key or a client ID. The following values are supported:
  • "ROOFTOP" restricts the results to addresses for which we have location information accurate down to street address precision.
  • "RANGE_INTERPOLATED" restricts the results to those that reflect an approximation (usually on a road) interpolated between two precise points (such as intersections). An interpolated range generally indicates that rooftop geocodes are unavailable for a street address.
  • "GEOMETRIC_CENTER" restricts the results to geometric centers of a location such as a polyline (for example, a street) or polygon (region).
  • "APPROXIMATE" restricts the results to those that are characterized as approximate.

If both result_type and location_type restrictions are present then the API will return only those results that matches both the result_type and the location_type restrictions.

Reverse Geocoding for a Latitude/Longitude

The following query contains the latitude/longitude value for a location in Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

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

The above query returns the following result:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "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" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional results[] ...

Note that the reverse geocoder returned more than one result. The "formatted_address" results 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 is shown below.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, 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 specific type of address, see the section below on restricting results by type.

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.

Reverse Geocoding for a Place ID

The following query contains the place ID of a place in Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

The above query returns the following result:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "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" ]
            }
         ],
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Reverse Geocoding Restricted by Type

The following example restricts the addresses returned to those with a location type of ROOFTOP and an address type of street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Note: These restrictions are only valid for reverse geocoding.

Reverse Geocoding Responses

The format of the reverse geocoding response is the same as the geocoding response. See Geocoding Responses. Below are the status codes possible in a reverse geocoding response.

Reverse Geocoding 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 reverse geocoding is not working. The "status" field may contain the following values:

• "OK" indicates that no errors occurred and at least one address was returned.
• "ZERO_RESULTS" indicates that the reverse geocoding was successful but returned no results. This may occur if the geocoder was passed a latlng in a remote location.
• "OVER_QUERY_LIMIT" indicates that you are over your quota.
• "REQUEST_DENIED" indicates that the request was denied. Possibly because the request includes a result_type or location_type parameter but does not include an API key or client ID.
• "INVALID_REQUEST" generally indicates one of the following:
  • The query (address, components or latlng) is missing.
  • An invalid result_type or location_type was given.
• "UNKNOWN_ERROR" indicates that the request could not be processed due to a server error. The request may succeed if you try again.

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.