Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share yourinput on your UI Kit experience.

Geocoder

Geocoderclass

google.maps.Geocoderclass

A service for converting between an address and aLatLng.

Access by callingconst {Geocoder} = await google.maps.importLibrary("geocoding").
SeeLibraries in the Maps JavaScript API.

Constructor

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

Methods

geocode
geocode(request[, callback])
Parameters: 
Return Value: Promise<GeocoderResponse>
Geocode a request.

GeocoderRequestinterface

google.maps.GeocoderRequestinterface

The specification for a geocoding request to be sent to theGeocoder.

Properties

addressoptional
Type: stringoptional
Address to geocode. One, and only one, ofaddress,location andplaceId must be supplied.
boundsoptional
LatLngBounds within which to search. Optional.
componentRestrictionsoptional
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.
BetaextraComputationsoptional

Notice: Available only in thev=beta channel.

A list of extra computations which may be used to complete the request. Note: These extra computations may return extra fields on the response.
fulfillOnZeroResultsoptional
Type: booleanoptional
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.
languageoptional
Type: stringoptional
A language identifier for the language in which results should be returned, when possible. See thelist of supported languages.
locationoptional
Type: LatLng|LatLngLiteraloptional
LatLng (orLatLngLiteral) for which to search. The geocoder performs a reverse geocode. See Reverse Geocoding for more information. One, and only one, ofaddress,location andplaceId must be supplied.
placeIdoptional
Type: stringoptional
The place ID associated with the location. Place IDs uniquely identify a place in the Google Places database and on Google Maps. Learn more aboutplace IDs in the Places API developer guide. The geocoder performs a reverse geocode. SeeReverse Geocoding for more information. One, and only one, ofaddress,location andplaceId must be supplied.
regionoptional
Type: stringoptional
Country code used to bias the search, specified as a two-character (non-numeric) Unicode region subtag / CLDR identifier. Optional. SeeGoogle Maps Platform Coverage Details for supported regions.

GeocoderComponentRestrictionsinterface

google.maps.GeocoderComponentRestrictionsinterface

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

Properties

administrativeAreaoptional
Type: stringoptional
Matches all theadministrative_area levels. Optional.
countryoptional
Type: stringoptional
Matches a country name or a two letter ISO 3166-1 country code. Optional.
localityoptional
Type: stringoptional
Matches against bothlocality andsublocality types. Optional.
postalCodeoptional
Type: stringoptional
Matchespostal_code andpostal_code_prefix. Optional.
routeoptional
Type: stringoptional
Matches the long or short name of aroute. Optional.

ExtraGeocodeComputationconstants

google.maps.ExtraGeocodeComputationconstants

Notice: Available only in thev=beta channel.

Extra computations to perform while completing a geocoding request.

Access by callingconst {ExtraGeocodeComputation} = await google.maps.importLibrary("geocoding").
SeeLibraries in the Maps JavaScript API.

Constants

ADDRESS_DESCRIPTORSGenerate an address descriptor.

GeocoderStatusconstants

google.maps.GeocoderStatusconstants

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

Access by callingconst {GeocoderStatus} = await google.maps.importLibrary("geocoding").
SeeLibraries in the Maps JavaScript API.

Constants

ERRORThere was a problem contacting the Google servers.
INVALID_REQUESTThisGeocoderRequest was invalid.
OKThe response contains a validGeocoderResponse.
OVER_QUERY_LIMITThe webpage has gone over the requests limit in too short a period of time.
REQUEST_DENIEDThe webpage is not allowed to use the geocoder.
UNKNOWN_ERRORA geocoding request could not be processed due to a server error. The request may succeed if you try again.
ZERO_RESULTSNo result was found for thisGeocoderRequest.

GeocoderResponseinterface

google.maps.GeocoderResponseinterface

A Geocoder response returned by theGeocoder containing the list ofGeocoderResults.

Properties

results
The list ofGeocoderResults.
Betaaddress_descriptoroptional

Notice: Available only in thev=beta channel.

Type: AddressDescriptoroptional
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 whenExtraGeocodeComputation.ADDRESS_DESCRIPTORS is enabled.
plus_codeoptional
Type: PlacePlusCodeoptional
The plus code associated with the location.

GeocoderResultinterface

google.maps.GeocoderResultinterface

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 aLatLng object.

Properties

address_components
An array ofGeocoderAddressComponents
formatted_address
Type: string
A string containing the human-readable address of this location.
geometry
AGeocoderGeometry 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 aboutPlace 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.
Betaaddress_descriptoroptional

Notice: Available only in thev=beta channel.

Type: AddressDescriptoroptional
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 whenExtraGeocodeComputation.ADDRESS_DESCRIPTORS is enabled, and only for certain localized places.
partial_matchoptional
Type: booleanoptional
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 beundefined.
plus_codeoptional
Type: PlacePlusCodeoptional
The plus code associated with the location.
postcode_localitiesoptional
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.

AddressDescriptorinterface

google.maps.AddressDescriptorinterface

Notice: Available only in thev=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.

GeocoderAddressComponentinterface

google.maps.GeocoderAddressComponentinterface

A single address component within aGeocoderResult. 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 foundhere

GeocoderGeometryinterface

google.maps.GeocoderGeometryinterface

Geometry information about thisGeocoderResult

Properties

location
Type: LatLng
The latitude/longitude coordinates of this result
location_type
The type of location returned inlocation
viewport
The bounds of the recommended viewport for displaying thisGeocoderResult
boundsoptional
Type: LatLngBoundsoptional
The precise bounds of thisGeocoderResult, if applicable

GeocoderLocationTypeconstants

google.maps.GeocoderLocationTypeconstants

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

Access by callingconst {GeocoderLocationType} = await google.maps.importLibrary("geocoding").
SeeLibraries in the Maps JavaScript API.

Constants

APPROXIMATEThe returned result is approximate.
GEOMETRIC_CENTERThe returned result is the geometric center of a result such a line (e.g. street) or polygon (region).
RANGE_INTERPOLATEDThe 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.
ROOFTOPThe returned result reflects a precise geocode.

Landmarkinterface

google.maps.Landmarkinterface

Notice: Available only in thev=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
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 seeTypes for more detail.
travel_distance_metersoptional
Type: numberoptional
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.

Areainterface

google.maps.Areainterface

Notice: Available only in thev=beta channel.

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

Properties

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.

Containmentconstants

google.maps.Containmentconstants

Notice: Available only in thev=beta channel.

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

Access by callingconst {Containment} = await google.maps.importLibrary("geocoding").
SeeLibraries in the Maps JavaScript API.

Constants

NEARThe target location is outside the area region, but close by.
OUTSKIRTSThe target location is within the area region, close to the edge.
WITHINThe target location is within the area region, close to the center.

SpatialRelationshipconstants

google.maps.SpatialRelationshipconstants

Notice: Available only in thev=beta channel.

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

Access by callingconst {SpatialRelationship} = await google.maps.importLibrary("geocoding").
SeeLibraries in the Maps JavaScript API.

Constants

ACROSS_THE_ROADThe target is directly opposite the landmark on the other side of the road.
AROUND_THE_CORNERNot on the same route as the landmark but a single turn away.
BEHINDClose to the landmark's structure but further away from its access point.
BESIDEThe target is directly adjacent to the landmark.
DOWN_THE_ROADOn the same route as the landmark but not besides or across.
NEARThis is the default relationship when nothing more specific below applies.
WITHINThe landmark has a spatial geometry and the target is within its bounds.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.