Geocoder

Geocoder class

google.maps.Geocoder class

A service for converting between an address and a LatLng.

Access by calling const {Geocoder} = await google.maps.importLibrary("geocoding").
See Libraries in the Maps JavaScript API.

Constructor
Geocoder	Geocoder() Parameters:  None Creates a new instance of a Geocoder that sends geocode requests to Google servers.

Methods
geocode	geocode(request[, callback]) Parameters:  request:  GeocoderRequest callback:  function(Array<GeocoderResult> optional, GeocoderStatus): void optional Return Value:  Promise<GeocoderResponse> Geocode a request.

GeocoderRequest interface

google.maps.GeocoderRequest interface

The specification for a geocoding request to be sent to the Geocoder.

Properties
address optional	Type:  string optional Address to geocode. One, and only one, of address, location and placeId must be supplied.
bounds optional	Type:  LatLngBounds|LatLngBoundsLiteral optional LatLngBounds within which to search. Optional.
componentRestrictions optional	Type:  GeocoderComponentRestrictions optional Components are used to restrict results to a specific area. A filter consists of one or more of: route, locality, administrativeArea, postalCode, country. 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. Optional.
extraComputations optional	Notice: Available only in the v=beta channel. Type:  Array<ExtraGeocodeComputation> optional A list of extra computations which may be used to complete the request. Note: These extra computations may return extra fields on the response.
fulfillOnZeroResults optional	Type:  boolean optional Fulfill the promise on a ZERO_RESULT status in the response. This may be desired because even with zero geocoding results there may still be additional response level fields returned.
language optional	Type:  string optional A language identifier for the language in which results should be returned, when possible. See the list of supported languages.
location optional	Type:  LatLng|LatLngLiteral optional LatLng (or LatLngLiteral) for which to search. The geocoder performs a reverse geocode. See Reverse Geocoding for more information. One, and only one, of address, location and placeId must be supplied.
placeId optional	Type:  string optional The place ID associated with the location. Place IDs uniquely identify a place in the Google Places database and on Google Maps. Learn more about place IDs in the Places API developer guide. The geocoder performs a reverse geocode. See Reverse Geocoding for more information. One, and only one, of address, location and placeId must be supplied.
region optional	Type:  string optional Country code used to bias the search, specified as a two-character (non-numeric) Unicode region subtag / CLDR identifier. Optional. See Google Maps Platform Coverage Details for supported regions.

GeocoderComponentRestrictions interface

google.maps.GeocoderComponentRestrictions interface

GeocoderComponentRestrictions represents a set of filters that resolve to a specific area. For details on how this works, see Geocoding Component Filtering.

Properties
administrativeArea optional	Type:  string optional Matches all the administrative_area levels. Optional.
country optional	Type:  string optional Matches a country name or a two letter ISO 3166-1 country code. Optional.
locality optional	Type:  string optional Matches against both locality and sublocality types. Optional.
postalCode optional	Type:  string optional Matches postal_code and postal_code_prefix. Optional.
route optional	Type:  string optional Matches the long or short name of a route. Optional.

ExtraGeocodeComputation constants

google.maps.ExtraGeocodeComputation constants

Notice: Available only in the v=beta channel.

Extra computations to perform while completing a geocoding request.

Access by calling const {ExtraGeocodeComputation} = await google.maps.importLibrary("geocoding").
See Libraries in the Maps JavaScript API.

Constants
ADDRESS_DESCRIPTORS	Generate an address descriptor.

GeocoderStatus constants

google.maps.GeocoderStatus constants

The status returned by the Geocoder on the completion of a call to geocode(). Specify these by value, or by using the constant's name. For example, 'OK' or google.maps.GeocoderStatus.OK.

Access by calling const {GeocoderStatus} = await google.maps.importLibrary("geocoding").
See Libraries in the Maps JavaScript API.

Constants
ERROR	There was a problem contacting the Google servers.
INVALID_REQUEST	This GeocoderRequest was invalid.
OK	The response contains a valid GeocoderResponse.
OVER_QUERY_LIMIT	The webpage has gone over the requests limit in too short a period of time.
REQUEST_DENIED	The webpage is not allowed to use the geocoder.
UNKNOWN_ERROR	A geocoding request could not be processed due to a server error. The request may succeed if you try again.
ZERO_RESULTS	No result was found for this GeocoderRequest.

GeocoderResponse interface

google.maps.GeocoderResponse interface

A Geocoder response returned by the Geocoder containing the list of GeocoderResults.

Properties
results	Type:  Array<GeocoderResult> The list of GeocoderResults.
address_descriptor optional	Notice: Available only in the v=beta channel. Type:  AddressDescriptor optional A relational description of a location. Includes a ranked set of nearby landmarks and the areas containing the target location. It is only populated for reverse geocoding requests and only when ExtraGeocodeComputation.ADDRESS_DESCRIPTORS is enabled.
plus_code optional	Type:  PlacePlusCode optional The plus code associated with the location.

GeocoderResult interface

google.maps.GeocoderResult interface

A single geocoder result retrieved from the geocode server. A geocode request may return multiple result objects. Note that though this result is "JSON-like," it is not strictly JSON, as it indirectly includes a LatLng object.

Properties
address_components	Type:  Array<GeocoderAddressComponent> An array of GeocoderAddressComponents
formatted_address	Type:  string A string containing the human-readable address of this location.
geometry	Type:  GeocoderGeometry A GeocoderGeometry object
place_id	Type:  string The place ID associated with the location. Place IDs uniquely identify a place in the Google Places database and on Google Maps. Learn more about Place IDs in the Places API developer guide.
types	Type:  Array<string> An array of strings denoting the type of the returned geocoded element. For a list of possible strings, refer to the Address Component Types section of the Developer's Guide.
address_descriptor optional	Notice: Available only in the v=beta channel. Type:  AddressDescriptor optional A relational description of the location associated with this geocode. Includes a ranked set of nearby landmarks and the areas containing the target location. This will only be populated for forward geocoding and place ID lookup requests, only when ExtraGeocodeComputation.ADDRESS_DESCRIPTORS is enabled, and only for certain localized places.
partial_match optional	Type:  boolean optional Whether the geocoder did not return an exact match for the original request, though it was able to match part of the requested address. If an exact match, the value will be undefined.
plus_code optional	Type:  PlacePlusCode optional The plus code associated with the location.
postcode_localities optional	Type:  Array<string> optional An array of strings denoting all the localities contained in a postal code. This is only present when the result is a postal code that contains multiple localities.

AddressDescriptor interface

google.maps.AddressDescriptor interface

Notice: Available only in the v=beta channel.

A relational description of a location. Includes a ranked set of nearby landmarks and the areas containing the target location.

Properties
areas	Type:  Array<Area> A ranked list of containing or adjacent areas. The most useful (recognizable and precise) areas are ranked first.
landmarks	Type:  Array<Landmark> A ranked list of nearby landmarks. The most useful (recognizable and nearby) landmarks are ranked first.

GeocoderAddressComponent interface

google.maps.GeocoderAddressComponent interface

A single address component within a GeocoderResult. A full address may consist of multiple address components.

Properties
long_name	Type:  string The full text of the address component
short_name	Type:  string The abbreviated, short text of the given address component
types	Type:  Array<string> An array of strings denoting the type of this address component. A list of valid types can be found here

GeocoderGeometry interface

google.maps.GeocoderGeometry interface

Geometry information about this GeocoderResult

Properties
location	Type:  LatLng The latitude/longitude coordinates of this result
location_type	Type:  GeocoderLocationType The type of location returned in location
viewport	Type:  LatLngBounds The bounds of the recommended viewport for displaying this GeocoderResult
bounds optional	Type:  LatLngBounds optional The precise bounds of this GeocoderResult, if applicable

GeocoderLocationType constants

google.maps.GeocoderLocationType constants

Describes the type of location returned from a geocode. Specify these by value, or by using the constant's name. For example, 'ROOFTOP' or google.maps.GeocoderLocationType.ROOFTOP.

Access by calling const {GeocoderLocationType} = await google.maps.importLibrary("geocoding").
See Libraries in the Maps JavaScript API.

Constants
APPROXIMATE	The returned result is approximate.
GEOMETRIC_CENTER	The returned result is the geometric center of a result such a line (e.g. street) or polygon (region).
RANGE_INTERPOLATED	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.
ROOFTOP	The returned result reflects a precise geocode.

Landmark interface

google.maps.Landmark interface

Notice: Available only in the v=beta channel.

A place that represents a point of reference for the address.

Properties
display_name	Type:  string The name for the landmark.
display_name_language_code	Type:  string The language of the name for the landmark.
place_id	Type:  string The Place ID of the underlying establishment serving as the landmark. Can be used to resolve more information about the landmark through Place Details or Place Id Lookup.
spatial_relationship	Type:  SpatialRelationship Defines the spatial relationship between the target location and the landmark.
straight_line_distance_meters	Type:  number The straight line distance between the target location and the landmark.
types	Type:  Array<string> One or more values indicating the type of the returned result. Please see Types for more detail.
travel_distance_meters optional	Type:  number optional The travel distance along the road network between the target location and the landmark. This can be unpopulated if the landmark is disconnected from the part of the road network the target is closest to OR if the target location was not actually considered to be on the road network.

Area interface

google.maps.Area interface

Notice: Available only in the v=beta channel.

A place that is a small region, such as a neighborhood, sublocality, or large complex that contains the target location.

Properties
containment	Type:  Containment Defines the spatial relationship between the target location and the area.
display_name	Type:  string The name for the area.
display_name_language_code	Type:  string The language of the name for the area.
place_id	Type:  string The Place ID of the underlying area. Can be used to resolve more information about the area through Place Details or Place ID Lookup.

Containment constants

google.maps.Containment constants

Notice: Available only in the v=beta channel.

An enum representing the spatial relationship between the area and the target location.

Access by calling const {Containment} = await google.maps.importLibrary("geocoding").
See Libraries in the Maps JavaScript API.

Constants
NEAR	The target location is outside the area region, but close by.
OUTSKIRTS	The target location is within the area region, close to the edge.
WITHIN	The target location is within the area region, close to the center.

SpatialRelationship constants

google.maps.SpatialRelationship constants

Notice: Available only in the v=beta channel.

An enum representing the relationship in space between the landmark and the target.

Access by calling const {SpatialRelationship} = await google.maps.importLibrary("geocoding").
See Libraries in the Maps JavaScript API.

Constants
ACROSS_THE_ROAD	The target is directly opposite the landmark on the other side of the road.
AROUND_THE_CORNER	Not on the same route as the landmark but a single turn away.
BEHIND	Close to the landmark's structure but further away from its access point.
BESIDE	The target is directly adjacent to the landmark.
DOWN_THE_ROAD	On the same route as the landmark but not besides or across.
NEAR	This is the default relationship when nothing more specific below applies.
WITHIN	The landmark has a spatial geometry and the target is within its bounds.