## [Geocoder](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#Geocoder) class class `google.maps.Geocoder` library `"geocoding"` A service for converting between an address and a `LatLng`. ```javascript const {Geocoder} = await google.maps.importLibrary("geocoding"); ``` | ### 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 optional, GeocoderStatus): void optional` **Return Value:** `Promise` Geocode a request. | ## [GeocoderRequest](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderRequest) interface interface `google.maps.GeocoderRequest` 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 | > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-beta-channel). **Type:** `Array 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](https://developers.google.com/maps/faq.md.txt#languagesupport). | | `location` optional | **Type:** `LatLng|LatLngLiteral optional` `LatLng` (or `LatLngLiteral`) for which to search. The geocoder performs a reverse geocode. See [Reverse Geocoding](https://developers.google.com/maps/documentation/javascript/geocoding.md.txt#ReverseGeocoding) 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](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) in the Places API developer guide. The geocoder performs a reverse geocode. See [Reverse Geocoding](https://developers.google.com/maps/documentation/javascript/geocoding.md.txt#ReverseGeocoding) 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](http://developers.google.com/maps/coverage.md.txt) for supported regions. | ## [GeocoderComponentRestrictions](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderComponentRestrictions) interface interface `google.maps.GeocoderComponentRestrictions` `GeocoderComponentRestrictions` represents a set of filters that resolve to a specific area. For details on how this works, see [Geocoding Component Filtering](https://developers.google.com/maps/documentation/javascript/geocoding.md.txt#ComponentFiltering). | ### 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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#ExtraGeocodeComputation) constants constants `google.maps.ExtraGeocodeComputation` library `"geocoding"` > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-beta-channel). Extra computations to perform while completing a geocoding request. These constants are also usable as strings. In TypeScript, the string literals are defined by the `ExtraGeocodeComputationString` type. ```javascript const {ExtraGeocodeComputation} = await google.maps.importLibrary("geocoding"); ``` | ### Constants || |---|---| | `ADDRESS_DESCRIPTORS` | Generate an address descriptor. | ## [GeocoderStatus](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderStatus) constants constants `google.maps.GeocoderStatus` library `"geocoding"` 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`. These constants are also usable as strings. In TypeScript, the string literals are defined by the `GeocoderStatusString` type. ```javascript const {GeocoderStatus} = await google.maps.importLibrary("geocoding"); ``` | ### 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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderResponse) interface interface `google.maps.GeocoderResponse` A Geocoder response returned by the `Geocoder` containing the list of `GeocoderResult`s. | ### Properties || |---|---| | `results` | **Type:** `Array` The list of `GeocoderResult`s. | | `address_descriptor` optional | > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderResult) interface interface `google.maps.GeocoderResult` 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` An array of `GeocoderAddressComponent`s | | `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](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) in the Places API developer guide. | | `types` | **Type:** `Array` An array of strings denoting the type of the returned geocoded element. For a list of possible strings, refer to the [Address Component Types](https://developers.google.com/maps/documentation/javascript/geocoding.md.txt#GeocodingAddressTypes) section of the Developer's Guide. | | `address_descriptor` optional | > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-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 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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#AddressDescriptor) interface interface `google.maps.AddressDescriptor` > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-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` A ranked list of containing or adjacent areas. The most useful (recognizable and precise) areas are ranked first. | | `landmarks` | **Type:** `Array` A ranked list of nearby landmarks. The most useful (recognizable and nearby) landmarks are ranked first. | ## [GeocoderAddressComponent](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderAddressComponent) interface interface `google.maps.GeocoderAddressComponent` 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` An array of strings denoting the type of this address component. A list of valid types can be found [here](https://developers.google.com/maps/documentation/javascript/geocoding.md.txt#GeocodingAddressTypes) | ## [GeocoderGeometry](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderGeometry) interface interface `google.maps.GeocoderGeometry` 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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#GeocoderLocationType) constants constants `google.maps.GeocoderLocationType` library `"geocoding"` 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`. These constants are also usable as strings. In TypeScript, the string literals are defined by the `GeocoderLocationTypeString` type. ```javascript const {GeocoderLocationType} = await google.maps.importLibrary("geocoding"); ``` | ### 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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#Landmark) interface interface `google.maps.Landmark` > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-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` One or more values indicating the type of the returned result. Please see [Types](https://developers.google.com/maps/documentation/places/web-service/supported_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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#Area) interface interface `google.maps.Area` > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#Containment) constants constants `google.maps.Containment` library `"geocoding"` > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-beta-channel). An enum representing the spatial relationship between the area and the target location. These constants are also usable as strings. In TypeScript, the string literals are defined by the `ContainmentString` type. ```javascript const {Containment} = await google.maps.importLibrary("geocoding"); ``` | ### 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](https://developers.google.com/maps/documentation/javascript/reference/geocoder.md.txt#SpatialRelationship) constants constants `google.maps.SpatialRelationship` library `"geocoding"` > [!WARNING] > **Notice:** Available only in the [v=beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#choosing-the-beta-channel). An enum representing the relationship in space between the landmark and the target. These constants are also usable as strings. In TypeScript, the string literals are defined by the `SpatialRelationshipString` type. ```javascript const {SpatialRelationship} = await google.maps.importLibrary("geocoding"); ``` | ### 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. |