AI-generated Key Takeaways

outlined_flag

• Reverse geocoding transforms geographic coordinates (latitude and longitude) into a human-readable address using thelatlng parameter.

• The response provides a list of potential addresses, each with details like formatted address, address components, geometry, place ID, and types.

• Filtering options likeresult_type andlocation_type refine results based on address and location preferences.

• While aiming for accuracy, reverse geocoding is an estimation, and results may vary in precision or returnZERO_RESULTS if no match is found.

• Understanding status codes likeOK,ZERO_RESULTS, and potential errors helps interpret the API's response effectively.

The termgeocoding generally refers to translating a human-readableaddress 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 asreverse geocoding.

Reverse geocoding requests

Required parameters

• latlng — The latitude and longitude coordinates specifying the location for which you want the closest, human-readable address.
• key — Your application's API key. This key identifies your application for purposes of quota management. Learn how toget a key.

Optional parameters

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

• language — The language in which to return results.
  • See thelist of supported languages. Google often updates the supported languages, so this list may not be exhaustive.
  • Iflanguage is not supplied, the geocoder attempts to use the preferred language as specified in theAccept-Language header, or the native language of the domain from which the request is sent.
  • The geocoder does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
  • If a name is not available in the preferred language, the geocoder uses the closest match.
• region — The region code, specified as a ccTLD ("top-level domain") two-character value. The parameter can also affect results based on applicable law.
• result_type — A filter of one or more address types, separated by a pipe (|). If the parameter contains multiple address types, the API returns all addresses that match any of the types. A note about processing: Theresult_type parameter does notrestrict the search to the specified address type(s). Rather, theresult_type acts as a post-search filter: the API fetches all results for the specifiedlatlng, then discards those results that do not match the specified address type(s).The following values are supported:

  Address types and address component types

  Thetypes array in theGeocodeResult body in the response indicates theaddress type. Examples of address types include a street address, a country, or a political entity. Thetypes array in theAddressComponents field of theGeocodeResult body indicates the type of each part of the address. Examples include street number or country.

  Addresses may have multiple types. The types may be considered 'tags'. For example, many cities are tagged with thepolitical andlocality types.

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

  Address Type	Description
  street_address	A precise street address.
  route	A named route (such as "US 101").
  intersection	A major intersection, usually of two major roads.
  political	A political entity. Usually, this type indicates a polygon of some civil administration.
  country	The national political entity, and is typically the highest order type returned by the Geocoder.
  administrative_area_level_1	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. In most cases,administrative_area_level_1 short names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data.
  administrative_area_level_2	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	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	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	A fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  administrative_area_level_6	A sixth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  administrative_area_level_7	A seventh-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  colloquial_area	A commonly-used alternative name for the entity.
  locality	An incorporated city or town political entity.
  sublocality	A first-order civil entity below a locality. For some locations may receive one of the additional types:sublocality_level_1 tosublocality_level_5. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area.
  neighborhood	A named neighborhood.
  premise	A named location, usually a building or collection of buildings with a common name.
  subpremise	An addressable entity below the premise level, such as an apartment, unit, or suite.
  plus_code	An encoded location reference, derived from latitude and longitude. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). Seehttps://plus.codes for details.
  postal_code	A postal code as used to address postal mail within the country.
  natural_feature	A prominent natural feature.
  airport	An airport.
  park	A named park.
  point_of_interest	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 "Eiffel Tower".

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

• location_type — A filter of one or more location types, separated by a pipe (|). If the parameter contains multiple location types, the API returns all addresses that match any of the types. A note about processing: Thelocation_type parameter does notrestrict the search to the specified location types. Rather, thelocation_type acts as a post-search filter: the API fetches all results for the specifiedlatlng, then discards those results that do not match the specified location types. The following values are supported:
  • "ROOFTOP" returns only the addresses for which Google has location information accurate down to street address precision.
  • "RANGE_INTERPOLATED" returns only the addresses 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" returns only geometric centers of a location such as a polyline (for example, a street) or polygon (region).
  • "APPROXIMATE" returns only the addresses that are characterized as approximate.
• extra_computations — Use this parameter to specify the following additional features in the response:
  • ADDRESS_DESCRIPTORS — See address descriptors for more details.
  • BUILDING_AND_ENTRANCES — See entrances and building outlines for more details.
  To enable multiple of these features for the same API request, include theextra_computations parameter in the request for each feature, for example:

  extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

If bothresult_type andlocation_type filters are present then the APIreturns only those results that match both theresult_type and thelocation_type values. If none of the filter values are acceptable, theAPI returnsZERO_RESULTS.

Example of reverse geocoding

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

{"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<code>results[]</code>...

{"plus_code":{"compound_code":"P27Q+MCM New York, NY, USA","global_code":"87G8P27Q+MCM"},"results":[{"formatted_address":"277 Bedford Ave, Brooklyn, NY 11211, USA",..."types":["street_address"]},{"formatted_address":"279 Bedford Ave, Brooklyn, NY 11211, USA",..."types":["premise"]},{"formatted_address":"277 Bedford Ave, Brooklyn, NY 11211, USA",..."types":["establishment","point_of_interest"]},{"formatted_address":"291-275 Bedford Ave, Brooklyn, NY 11211, USA",..."types":["route"]},{"formatted_address":"P27Q+MC New York, NY, USA",..."types":["plus_code"]},{"formatted_address":"South Williamsburg, Brooklyn, NY, USA",..."types":["neighborhood","political"]},{"formatted_address":"Brooklyn, NY 11211, USA",..."types":["postal_code"]},{"formatted_address":"Williamsburg, Brooklyn, NY, USA",..."types":["neighborhood","political"]},{"formatted_address":"Kings County, Brooklyn, NY, USA",..."types":["administrative_area_level_2","political"]},{"formatted_address":"Brooklyn, NY, USA",..."types":["political","sublocality","sublocality_level_1"]},{"formatted_address":"New York, NY, USA",..."types":["locality","political"]},{"formatted_address":"New York, USA",..."types":["administrative_area_level_1","political"]},{"formatted_address":"United States",..."types":["country","political"]}],"status":"OK"}

This API returns different types of addresses, from the most specific street address to less specific political entities such as neighborhoods, cities, counties, and states. The more exact address is generally most prominent result, as it is in this case. If you want to match a specific type of address, see the section below onrestricting results by type. Because of this, the location of the results relative to each other can vary.

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

The format of the reverse geocoding response is the same as the Geocodingresponse. SeeGeocoding responses.Below are the status codes possible in a reverse geocoding response.

Reverse geocoding status codes

The"status" field within the Geocoding response object containsthe status of the request, and may contain debugging information to help youtrack 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 alatlng 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 aresult_type orlocation_type parameter but does not include an API key.
• "INVALID_REQUEST" generally indicates one of the following:
  • The query (address,components orlatlng) is missing.
  • An invalidresult_type orlocation_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.

Reverse geocoding plus codes

Theplus_code field within the Geocoding response contains a plus code thatbest approximates the queried latitude and longitude.In addition, the JSON results array in most cases contains a full Geocodingresult with aplus_code type and an address containing a pluscode. The distance between the decoded plus code and the request point isguaranteed to be under 10 meters.