Reverse geocoding translates a map location into a human-readableaddress. You represent the map location by the latitude and longitudecoordinates of the location.

When you reverse geocode a location, the response contains the:

• Place ID of theaddress
• Plus Codes of the address
• Address details

This API returns different types of addresses, from the most specific streetaddress to less specific political entities such as neighborhoods, cities,counties, and states. The most exact address is generally the first result. Ifyou want to match a specific type of address, use thetypes parameter.

Areverse geocodingrequest is an HTTP GET request. You can specify the locationas anunstructured string:

https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE

Or as astructured set of latitude and longitudecoordinates represented by query parameters:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

You typically use the structured format when processing location componentscaptured in an HTML form.

Pass all other parameters as URL parameters or, for parameters such as the APIkey or field mask, in headers as part of the GET request. For example:

Pass an unstructured location string

An unstructured location is a location formatted as a comma-separated string oflatitude and longitude coordinates:

https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?key=API_KEY

Or in a curl command:

curl -X GET -H 'Content-Type: application/json' \-H "X-Goog-Api-Key:API_KEY" \"https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338"

Pass a structured location

Specify the structured location by using thelocation query parameter, of typeLatLng.TheLatLng object lets you specify the latitude and longitude as separatequery parameters:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Use OAuth to make a request

Geocoding API v4 supportsOAuth2.0 for authentication. To use OAuthwith the Geocoding API, the OAuth token must be assigned the correct scope.Geocoding API supports the following scopes for use with reverse geocoding:

• https://www.googleapis.com/auth/maps-platform.geocode — Use with all Geocoding API endpoints.
• https://www.googleapis.com/auth/maps-platform.geocode.location — Use only withGeocodeLocation for reverse geocoding.

Also, you can use the generalhttps://www.googleapis.com/auth/cloud-platformscope for all Geocoding API endpoints. That scope is useful duringdevelopment, but not production, because it is a general scope that allowsaccess to all endpoints.

For more information and examples, seeUseOAuth.

Reverse geocoding response

Reverse geocoding returns aGeocodeLocationResponseobject that contains:

• Theresults array ofGeocodeResultobjects that represents the place.

  The reverse geocoder returns more than one result in theresults array.The results are not just postal addresses, but any way to geographicallyname 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). Allare "addresses" to the geocoder. The reverse geocoder returns any of thesetypes as valid results.

• TheplusCode field, of typePlusCode, contains the Plus Code that bestapproximates the latitude and longitude in the request. In addition, eachelement of theresults array contains a Plus Code. The distance betweenthe decoded Plus Code and the request point is under 10 meters.

  Note: The API does not always return Plus Codes.

The complete JSON object is in the form:

{"results":[{"place":"//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU","placeId":"ChIJV-FZF7i7j4ARo4ZOUoecZFU","location":{"latitude":37.422588300000008,"longitude":-122.0846489},"granularity":"ROOFTOP","viewport":{"low":{"latitude":37.421239319708512,"longitude":-122.0859978802915},"high":{"latitude":37.423937280291511,"longitude":-122.08329991970851}},"formattedAddress":"1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA","addressComponents":[{"longText":"1600","shortText":"1600","types":["street_number"]},{"longText":"Amphitheatre Parkway","shortText":"Amphitheatre Pkwy","types":["route"],"languageCode":"en"},{"longText":"Mountain View","shortText":"Mountain View","types":["locality","political"],"languageCode":"en"},{"longText":"Santa Clara County","shortText":"Santa Clara County","types":["administrative_area_level_2","political"],"languageCode":"en"},{"longText":"California","shortText":"CA","types":["administrative_area_level_1","political"],"languageCode":"en"},{"longText":"United States","shortText":"US","types":["country","political"],"languageCode":"en"},{"longText":"94043","shortText":"94043","types":["postal_code"]}],"types":["street_address"],"plusCode":{"globalCode":"849VCW83+PM","compoundCode":"CW83+PM Mountain View, CA, USA"}},{"place":"//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw","placeId":"ChIJj61dQgK6j4AR4GeTYWZsKWw","location":{"latitude":37.4220541,"longitude":-122.08532419999999},"granularity":"ROOFTOP","viewport":{"low":{"latitude":37.4207051197085,"longitude":-122.08667318029148},"high":{"latitude":37.423403080291493,"longitude":-122.08397521970851}},"formattedAddress":"1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA","addressComponents":[{"longText":"1600","shortText":"1600","types":["street_number"]},{"longText":"Amphitheatre Parkway","shortText":"Amphitheatre Pkwy","types":["route"],"languageCode":"en"},{"longText":"Mountain View","shortText":"Mountain View","types":["locality","political"],"languageCode":"en"},{"longText":"Santa Clara County","shortText":"Santa Clara County","types":["administrative_area_level_2","political"],"languageCode":"en"},{"longText":"California","shortText":"CA","types":["administrative_area_level_1","political"],"languageCode":"en"},{"longText":"United States","shortText":"US","types":["country","political"],"languageCode":"en"},{"longText":"94043","shortText":"94043","types":["postal_code"]}],"types":["establishment","point_of_interest"],"plusCode":{"globalCode":"849VCWC7+RV","compoundCode":"CWC7+RV Mountain View, CA, USA"}},...],"plusCode":{"globalCode":"849VCWF8+24H","compoundCode":"CWF8+24H Mountain View, CA, USA"}}

• languageCode

  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.
  • IflanguageCode is not supplied, the API defaults toen. If you specify an invalid language code, the API returns anINVALID_ARGUMENT error.
  • The API 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 API uses the closest match.
  • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another.

• regionCode

  The region code as a two-character CLDR code value. There is no default value. Most CLDR codes are identical to ISO 3166-1 codes.

  When geocoding an address,forward geodcoding, this parameter can influence, but not fully restrict, results from the service to the specified region. When geocoding a location or a place,reverse geocoding orplace geocoding, this parameter can be used to format the address. In all cases, this parameter can affect results based on applicable law.

• granularity

  One or more location granularities, specified as separate query parameters, as defined byGranularity. If you specify multiplegranularity parameters, the API returns all addresses that match any of the granularities.

  Thegranularity parameter does notrestrict the search to the specified location granularities. Rather,granularity acts as a post-search filter. The API fetches all results for the specifiedlocation, then discards those results that don't match the specified location granularities.

  If you specify bothtypes andgranularity then the API returns only those results that match both. For example:

  https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

• types

  One or more address types, specified as separate query parameters. If you specify multipletypes parameters, the API returns all addresses that match any of the types.

  Thetypes parameter does notrestrict the search to the specified address type(s). Rather,types acts as a post-search filter. The API fetches all results for the specified location, then discards those results that don't match the specified address type(s).

  If you specify bothtypes andgranularity then the API returns only those results that match both. For example:

  https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

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