Geocoding Service

Overview

Geocoding is the process of converting addresses (like
"1600 Amphitheatre Parkway, Mountain View, CA") into geographic coordinates
(like latitude 37.423021 and longitude -122.083739), which you can use to
place markers or position the map.

Reverse geocoding is the
process of converting geographic coordinates into a human-readable
address.

You can also use the geocoder to find the address for a
given place ID.

The Maps JavaScript API provides a geocoder class for
geocoding and reverse geocoding dynamically from user input. If instead
you wish to geocode static, known addresses, see the
Geocoding web service.

This page describes the client-side service available with the
Maps JavaScript API. If you want to work with Google Maps
web services on your server, take a look at the
Node.js Client for Google Maps Services. The page at
that link also introduces the Java Client,
Python Client and Go Client for Google Maps Services.

Getting started

Before using the Geocoding service in the Maps JavaScript API, first ensure
that the Geocoding API is enabled in the Google Cloud Platform Console, in the same
project you set up for the Maps JavaScript API.

Click the Select a project button, then select the same project you set up
for the Maps JavaScript API and click Open.

From the list of APIs on the Dashboard, look for
Geocoding API.

If you see the API in the list, you’re all set. If the API is not listed,
enable it:

At the top of the page, select ENABLE API to display the
Library tab. Alternatively, from the left side menu,
select Library.

Search for Geocoding API, then select it from the
results list.

Select ENABLE. When the process finishes,
Geocoding API appears in the list of APIs on the
Dashboard.

Pricing and policies

Effective July 16, 2018, a new pay-as-you-go pricing plan went into effect
for Maps, Routes, and Places. To learn more about the new pricing and usage
limits for your use of the JavaScript Geocoding service, see
Usage and Billing
for the Geocoding API.

Use of the Geocoding service for existing Premium Plan
customers

In order to switch over to the new pay as you go pricing plan, you must
create a new project, as your existing Premium project cannot be transferred.
You must get new API keys, and use them to to replace your existing keys.
Please contact your account manager and/or reseller to coordinate your
transition to the new plan before your current Premium license expires. In the
meantime, your
Premium Plan quotas remain in effect.

Unlimited client-side requests per second, per Premium Plan project.*
Note that
the server-side API is limited
to 50 requests per second.

Rate limits on additional requests with the Standard Plan and
Premium Plan

* Note: The additional rate limit is applied per user session, regardless
of how many users share the same project. When you first load the API, you are allocated
an initial quota of requests. Once you use this quota, the API enforces rate limits on
additional requests on a per-second basis. If too many requests are made within a certain
time period, the API returns an OVER_QUERY_LIMIT response code.

The per-session rate limit prevents the use of client-side services for batch
requests, such as batch geocoding. For batch requests, use the
Geocoding API
web service.

Policies

Geocoding Requests

Accessing the Geocoding service is asynchronous, since the Google Maps API
needs to make a call to an external server. For that reason, you need to pass
a callback method to execute upon completion of the request. This
callback method processes the result(s). Note that the geocoder may return
more than one result.

You access the Google Maps API geocoding service within your code via the
google.maps.Geocoder constructor object. The
Geocoder.geocode() method initiates a request to the geocoding
service, passing it a GeocoderRequest object literal containing
the input terms and a callback method to execute upon receipt of the response.

Required parameters: You must supply one, and only one, of
the following fields:

address — The address which you want to geocode.
orlocation — The LatLng (or
LatLngLiteral) for which you wish to obtain the closest,
human-readable address. The geocoder performs a reverse geocode.
See
Reverse Geocoding for more information.
orplaceId — The place ID of the place for which you wish
to obtain the closest, human-readable address. See more about
retrieving an address for a place ID.

Optional parameters:

bounds — The LatLngBounds within which to
bias geocode results more prominently. The bounds parameter
will only influence, not fully restrict, results from the geocoder. See
more information about
viewport biasing below.

componentRestrictions — Used to restrict results to a
specific area. See more information about
component filtering below.

region — The region code, specified as a
IANA
language region subtag. In most cases, these tags map
directly to familiar ccTLD ("top-level domain") two-character values. The
region parameter will only influence, not fully restrict,
results from the geocoder. See more information about
region code biasing below.

Geocoding Responses

The Geocoding service requires a callback method to execute upon retrieval
of the geocoder's results. This callback should pass two parameters to hold
the results and a status code, in that order.

Geocoding Results

The GeocoderResult object represents a single
geocoding result. A geocode request may return multiple result objects:

types[] is an array indicating the address type of
the returned result. This array contains a set of zero or more tags
identifying the type of feature returned in the result. For example, a
geocode of "Chicago" returns "locality" which indicates that "Chicago" is a
city, and also returns "political" which indicates it is a political
entity. See more information about
address types and address component
types below.

formatted_address is a string containing the human-readable
address of this location.

Often this address is equivalent to the postal address. Note that some
countries, such as the United Kingdom, do not allow distribution of true
postal addresses due to licensing restrictions.

The formatted address is logically composed of one or more address
components. For example, the address "111 8th Avenue, New York, NY"
consists of the following components: "111" (the street number),
"8th Avenue" (the route), "New York" (the city) and "NY" (the US state).

Do not parse the formatted address programmatically. Instead you should use
the individual address components, which the API response includes in addition
to the formatted address field.

address_components[] is an array containing the separate
components applicable to this address.

Each address component typically contains the following fields:

types[] is an array indicating the type of the
address component. See the list of
supported types.

long_name is the full text description or name of the
address component as returned by the Geocoder.

short_name is an abbreviated textual name for the address
component, if available. For example, an address component for the state
of Alaska may have a long_name of "Alaska" and a
short_name of "AK" using the 2-letter postal abbreviation.

Note the following facts about the address_components[]
array:

The array of address components may contain more components than the
formatted_address.

The array does not necessarily include all the political entities that
contain an address, apart from those included in the
formatted_address. To retrieve all the political entities
that contain a specific address, you should use reverse geocoding, passing
the latitude/longitude of the address as a parameter to the request.

The format of the response is not guaranteed to remain the same between
requests. In particular, the number of address_components
varies based on the address requested and can change over time for the
same address. A component can change position in the array.
The type of the component can change. A particular component may be
missing in a later response.

partial_match indicates that the geocoder did not return
an exact match for the original request, though it was able to match part of
the requested address. You may wish to examine the original request for misspellings and/or
an incomplete address.

Partial matches most often occur for street addresses that do not exist
within the locality you pass in the request. Partial matches may also be
returned when a request matches two or more locations in the same locality.
For example, "21 Henr St, Bristol, UK" will return a partial match for both
Henry Street and Henrietta Street. Note that if a request includes a
misspelled address component, the geocoding service may suggest an alternative
address. Suggestions triggered in this way will also be marked as a partial
match.

place_idis a unique identifier of a place, which can be used
with other Google APIs. For example, you can use the place_id
with the Google Places
API library to get details of a local business, such as phone number,
opening hours, user reviews, and more. See the
place ID overview.

postcode_localities[] is an array denoting all the localities
contained in a postal code, and is only present when the result is a postal
code that contains multiple localities. This array can contain up to 10
localities.

geometry contains the following information:

location contains the geocoded latitude,longitude value.
Note that we return this location as a LatLng object, not
as a formatted string.

location_type stores additional data about the specified
location. The following values are currently supported:

ROOFTOP indicates
that the returned result reflects a precise geocode.

RANGE_INTERPOLATED
indicates that 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.

GEOMETRIC_CENTER
indicates that the returned result is the geometric center of a
result such as a polyline (for example, a street) or polygon
(region).

APPROXIMATE
indicates that the returned result is approximate.

viewport stores the recommended viewport for the
returned result.

bounds (optionally returned) stores the
LatLngBounds which can fully contain the returned result.
Note that these bounds may not match the recommended viewport. (For
example, San Francisco includes the
Farallon
Islands, which are technically part of the city, but should not
be returned in the viewport.)

The addresses will be returned by the Geocoder using the browser's preferred
language setting, or the language specified when loading the API JavaScript
using the language parameter. (For more information, see
Localization.)

Address Types and Address Component Types

The types[] array in the
GeocoderResult
indicates the
address type. The types[] array may also be returned
within a
GeocoderAddressComponent
to indicate the type of the particular address component. Addresses returned
by the geocoder may have multiple types; the types may be considered tags.
For example, many cities are tagged with the political and
locality type.

The following types are supported and returned by the geocoder in both the
address types and address component types:

street_address indicates a precise street address.

route indicates a named route (such as "US 101").

intersection indicates a major intersection, usually of two
major roads.

political indicates a political entity. Usually, this type
indicates a polygon of some civil administration.

country indicates the national political entity, and is
typically the highest order type returned by the Geocoder.

administrative_area_level_1 indicates 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 indicates 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 indicates 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 indicates 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 indicates a fifth-order civil
entity below the country level. This type indicates a minor civil division.
Not all nations exhibit these administrative levels.

colloquial_area indicates a commonly-used alternative name
for the entity.

locality indicates an incorporated city or town political
entity.

sublocality indicates a first-order civil entity below a
locality. For some locations may receive one of the additional types:
sublocality_level_1 to sublocality_level_5.
Each sublocality level is a civil entity. Larger numbers indicate a smaller
geographic area.

neighborhood indicates a named neighborhood

premise indicates a named location, usually a building or
collection of buildings with a common name

subpremise indicates a first-order entity below a named
location, usually a singular building within a collection of buildings with
a common name

postal_code indicates a postal code as used to address postal
mail within the country.

natural_feature indicates a prominent natural feature.

airport indicates an airport.

park indicates a named park.

point_of_interest indicates 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.

In addition to the above, address components may include the types below.

Note: This list is not exhaustive, and is
subject to change.

floor indicates the floor of a building address.

establishment typically indicates a place that has not yet
been categorized.

point_of_interest indicates a named point of interest.

parking indicates a parking lot or parking structure.

post_box indicates a specific postal box.

postal_town indicates a grouping of geographic areas, such as
locality and sublocality, used for mailing addresses
in some countries.

room indicates the room of a building address.

street_number indicates the precise street number.

bus_station, train_station and
transit_station indicate the location of a bus, train or public
transit stop.

Status Codes

The status code may return one of the following values:

"OK" indicates that no errors occurred; the address was successfully parsed and at
least one geocode was returned.

"ZERO_RESULTS" indicates that the geocode was successful but returned no results.
This may occur if the geocoder was passed a non-existent address.

"OVER_QUERY_LIMIT" indicates that you are over your quota.

"REQUEST_DENIED" indicates that your request was denied.

"INVALID_REQUEST" generally indicates that the query (address,
components or latlng) is missing.

"UNKNOWN_ERROR" indicates that the request could not be
processed due to a server error. The request may succeed if you
try again.

"ERROR" indicates that the request timed out or there was a
problem contacting the Google servers. The request may succeed if you
try again.

In this example, we geocode an address and place a marker at the returned
latitude and longitude values. Note that the handler is passed as an
anonymous function literal.

Viewport Biasing

You can instruct the Geocoding Service to prefer results within a given
viewport (expressed as a bounding box). You do so by setting the
bounds parameter within the GeocoderRequest object
literal to define the bounds of this viewport. Note that biasing only
prefers results within the bounds; if more relevant results exist
outside of these bounds, they may be included.

For example, a geocode for "Winnetka" generally returns this suburb of Chicago:

Region Code Biasing

You can set the Geocoding Service to return results biased to a
particular region explicitly using the region parameter. This
parameter takes a region code, specified as a IANA language
region subtag. In most cases, these tags map directly to
familiar ccTLD ("top-level domain") two-character values such as "uk" in
"co.uk" for example. In some cases, the region tag also supports
ISO-3166-1 codes, which sometimes differ from ccTLD values ("GB" for "Great
Britain" for example).

Geocoding requests can be sent for every domain in which the main
Google Maps application offers geocoding. Note that biasing only
prefers results for a specific domain; if more relevant results
exist outside of this domain, they may be included.

For example, a geocode for "Toledo" returns this result, as the default
domain for the Geocoding Service is set to the United States:

Component Filtering

You can set the Geocoding Service to return address results restricted
to a specific area, by using a components filter. Specify the filter in the
componentRestrictions parameter. Filter values support the
same methods of spelling correction and partial matching as other geocoding
requests.

The geocoder returns only the results that match all the component
filters. That is, it evaluates the filter specifications as an AND, not an
OR.

A components filter consists of one or more of the following items:

route matches long or short name of a route.

locality matches against locality and sublocality types.

administrativeArea matches all the
levels of administrative area.

postalCode matches postal codes and postal code prefixes.

country matches a country name or a two letter
ISO 3166-1
country code. Note: The API follows the ISO standard for
defining countries, and the filtering works best when using the
corresponding ISO code of the country.

The following example demonstrates using the
componentRestrictions parameter to filter by
country and postalCode:

Reverse Geocoding (Address Lookup)

The term geocoding generally refers to translating a human-readable
address into a location on a map. The process of doing the converse,
translating a location on the map into a human-readable address, is known as
reverse geocoding.

Instead of supplying a textual address, supply a comma-separated
latitude/longitude pair in the location parameter.

The following example geocodes a latitude/longitude value and centers the
map at that location, bringing up an info window with the formatted address:

Note that in the previous example we showed the first result by
selecting results[0]. The reverse geocoder often returns more
than one result. Geocoded addresses are not just postal addresses, but any
way to geographically name a location. For example, when geocoding a point in
the city of Chicago, the geocoded point may be labeled as a street address,
as the city (Chicago), as its state (Illinois) or as a country (The United
States). All are addresses to the geocoder. The reverse geocoder returns all
of these results.

Addresses are returned in the order of best to least matches. Generally,
the more exact address is the most prominent result, as it is in this case.
Note that we return different types of addresses, from the most specific
street address to less specific political entities such as neighborhoods,
cities, counties, states, etc. If you wish to match a more general address,
you may wish to inspect the results[].types field.

Note: Reverse geocoding is not an exact
science. The geocoder will attempt to find the closest addressable location
within a certain tolerance.

Retrieving an Address for a Place ID

Supply a placeId to find the address for a given place ID. The
place ID is a unique identifier that can be used with other Google APIs. For
example, you can supply the placeId returned by the
Roads API to get the
address for a snapped point. For more information about place IDs, see the
place ID overview.

When you supply a placeId, the request cannot contain any of
the following fields:

address

latLng

location

componentRestrictions

The following example accepts a place ID, finds the corresponding address,
and centers the map at that location. It also brings up an info window showing
the formatted address of the relevant place: