What Is Geocoding?: Geocoding Is The Process of Converting Addresses (Like "1600 Amphitheatre Parkway

15/09/2021, 06:53 Overview
| Geocoding API | Google Developers
Overview bookmark_border
ervice is also available as part of the client-side

Maps JavaScript API
ps/documentation/javascript/geocoding),
or for server-side use with the
Java Client,
Python Client, Go Clie
ode.js Client for Google Maps Services (/maps/documentation/geocoding/client-library).
What is geocoding?
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 on a map, or position the map.
Reverse geocoding (#ReverseGeocoding) is the

process of converting geographic coordinates
into a human-readable
address.
You can also use the Geocoding API to find the address for a
given place ID (#place-id).
The Geocoding API provides a direct way to access these services

via an HTTP request.
The following example uses the Geocoding service through the
Maps JavaScript API to
demonstrate the basic functionality.
Enter a query to geocode, or click on the map to reverse geocode.

Geocode
chevron_left
1000 km
Map data ©2021 Google, INEGI
https://developers.google.com/maps/documentation/geocoding/overview?hl=en_US 1/36
15/09/2021, 06:53 Overview | Geocoding API | Google Developers
View this example

fullscreen (/maps/documentation/utils/geocoder) to see additional
functionality of the Geocoding API, such as more options available
for tailoring the request
(component filtering and viewport biasing) and more
details about each result.
Before you begin
This document describes the Geocoding API web service. It is intended for website
and
mobile developers who want to use geocoding data within maps provided by one of the
Google Maps Platform APIs.
Note: This service is generally designed for geocoding

static (known in advance)
addresses for placement of application
content on a map; this service is not designed to
respond in real time to user
input. For dynamic geocoding (for example, within a user
interface element), consult
the documentation for the Maps JavaScript API client geocoder
(/maps/documentation/javascript/geocoding) and/or the
Google Play services Location APIs
(https://developer.android.com/google/play-services/location.html).
Before you start developing with the Geocoding API, review the
authentication requirements
(/maps/documentation/geocoding/get-api-key) (you need
an API key) and the API usage and
billing (/maps/documentation/geocoding/usage-and-billing) information (you need to enable
billing on your project).
Geocoding API request format
A Geocoding API request takes the following form:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
where outputFormat may be either of the following values:
json (recommended) indicates output in JavaScript Object

Notation (JSON); or
xml indicates output in XML
HTTPS is required for requests that use an API key.
Note: URLs must be

properly encoded
(/maps/documentation/geocoding/web-service-best-practices#BuildingURLs)
to be valid and are
chevron_left
limited to 8192 characters for all web services.
Be aware of this limit when constructing
your URLs. Note that different browsers,

proxies, and servers may have different URL
character limits as well.
Some parameters are required while some are optional. As is standard in URLs,
parameters
are separated using the ampersand (&) character.
The rest of this page describes geocoding (#geocoding) and

reverse geocoding
(#ReverseGeocoding) separately, because
different parameters are available for each type of
request.
Geocoding (latitude/longitude lookup)
erved characters (for example the plus sign "+") must be

URL-encoded
ps/documentation/geocoding/web-service-best-practices#BuildingURLs).
Required parameters in a geocoding request:
address — The street address or plus code (https://plus.codes)

that you want to
geocode. Specify addresses in accordance with the format
used by the national
postal service of the country concerned. Additional
address elements such as
business names and unit, suite or floor numbers
should be avoided. Street address
elements should be delimited by spaces
(shown here as url-escaped to %20):
address=24%20Sussex%20Drive%20Ottawa%20ON
Format plus codes as shown here (plus signs are url-escaped to %2B and spaces are
url-escaped to %20):
global code is a 4 character area code and 6 character or longer

local code
(849VCWC8+R9 is 849VCWC8%2BR9).
compound code is a 6 character or longer local code with an

explicit location
(CWC8+R9 Mountain View, CA, USA is
CWC8%2BR9%20Mountain%20View%20CA%20USA).
--OR--
components — A components filter with elements

separated by a pipe (|). The
chevron_left
components filter is also accepted
as an optional parameter if an address is
provided.
Each element in the components filter consists of a
component:value pair,
and fully restricts the results
from the geocoder. See more information about
component filtering (#component-filtering) below.
key — Your application's API key. This key identifies

your application for purposes of
quota management. Learn how to
get a key (/maps/documentation/geocoding/get-api-key).
Please refer to the FAQ (/maps/faq#geocoder_queryformat) for

additional guidance.
Optional parameters in a Geocoding request:
bounds — The bounding box of the viewport

within which to bias geocode results
more prominently. This parameter will
only influence, not fully restrict, results from the
geocoder. (For more
information see Viewport Biasing (#Viewports) below.)
language — The language in which to

return results.
See the list of supported

languages (/maps/faq#languagesupport). Google often
updates the supported languages, so this
list may not be exhaustive.
If language is not supplied, the geocoder attempts to

use the preferred
language as specified in the
Accept-Language header, or the native language of
the
domain from which the request is sent.
The geocoder 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 geocoder 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. For example, utca
and tér are synonyms for street and square
respectively
in Hungarian.
region — The region code, specified as a ccTLD

("top-level domain") two-character
value. This parameter will only
influence, not fully restrict, results from the geocoder.
(For more
information see Region Biasing (#RegionCodes) below.)
chevron_left
components — A components filter with elements

separated by a pipe (|). The
components filter is
required if the request doesn't include an address.
Each element
in the components filter consists of a
component:value pair, and fully restricts the
results
from the geocoder. See more information about
component filtering
(#component-filtering) below.
Geocoding responses
Geocoding responses are returned in the format indicated by the

output flag within the URL
request's path.
In this example, the Geocoding API requests a json response for

a query on "1600
Amphitheatre Parkway, Mountain View, CA".
This request demonstrates using the JSON output flag:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Pa
+Mountain+View,+CA&key= YOUR_API_KEY
This request demonstrates using the XML output flag:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Pa
+Mountain+View,+CA&key= YOUR_API_KEY
Click the tabs below to see the sample JSON and XML responses.
JSONXML (#xml)
(#json)
{
"results" : [
{
"address_components" : [
{
"long_name" : "1600",
"short_name" : "1600",
"types" : [ "street_number" ]
}, chevron_left
{
"long_name" : "Amphitheatre Pkwy",
"short_name" : "Amphitheatre Pkwy",
"types" : [ "route" ]
},
{
"long_name" : "Mountain View",
"short_name" : "Mountain View",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Clara County",
"short_name" : "Santa Clara County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "California",
"short_name" : "CA",
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "94043",
"short_name" : "94043",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "1600 Amphitheatre Parkway, Mountain View
"geometry" : {
"location" : {
"lat" : 37.4224764,
"lng" : -122.0842499
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 37.4238253802915,
"lng" : -122.0829009197085
},
"southwest" : {
"lat" : 37.4211274197085,
"lng" : -122.0855988802915
}
} chevron_left
},
"place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
"plus_code": {
"compound_code": "CWC8+W5 Mountain View, California, United
"global_code": "849VCWC8+W5"
},
"types" : [ "street_address" ]
}
],
"status" : "OK"
}
Note that the JSON response contains two root elements:
"status" contains metadata on the request. See

Status codes (#StatusCodes) below.
"results" contains an array of geocoded address information and

geometry information.
Generally, only one entry in the "results" array is returned for

address lookups,though the
geocoder may return several results when address
queries are ambiguous.
Status codes
The "status" field within the Geocoding response object contains the status
of the
request, and may contain debugging information to help you track down why geocoding
is
not working. The "status" field may contain 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_DAILY_LIMIT indicates any of the following:
The API key is missing or invalid.
Billing has not been enabled on your account.
A self-imposed usage cap has been exceeded.
The provided method of payment is no longer valid (for example, a

credit card
has expired).
See the Maps FAQ (/maps/faq#over-limit-key-error) to learn

how to fix this.
chevron_left
"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 messages
When the geocoder returns a status code other than OK, there may be an additional
error_message field within the Geocoding response object. This field contains more
detailed information about the reasons behind the given status code.
This field is not guaranteed to be always present, and its

content is subject to change.
Results
When the geocoder returns results, it places them within a (JSON) results
array. Even if
the geocoder returns no results (such as if the address doesn't exist) it still
returns an
empty results array. (XML responses consist of zero or more
<result> elements.)
A typical result contains the following fields:
The types[] array indicates the 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.
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 formattedchevron_left

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 (/maps/documentation/places/web-service/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.
To handle the array of components, you should parse the response

and select
appropriate values via expressions. See the guide to
parsing a response
(/maps/documentation/geocoding/web-service-best-practices#Parsing).
postcode_localities[] is an array denoting all the localities

contained in a postal
code. This is only present when the result is a postal
code that contains multiple
localities.
geometry contains the following information:
location contains the geocoded latitude, longitude value. For normal

address
chevron_left
lookups, this field is typically the most important.
location_type stores additional data about the specified location. The

following values are currently supported:
"ROOFTOP" indicates that the returned result is a precise geocode for

which we have location information accurate down to street address
precision.
"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 contains the recommended viewport for displaying

the returned
result, specified as two latitude,longitude values defining the
southwest and
northeast corner of the viewport bounding box. Generally the
viewport is used
to frame a result when displaying it to a user.
bounds (optionally returned) stores the bounding box

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
(https://en.wikipedia.org/wiki/Farallon_Islands), which
are technically part of the city,
but probably should not be returned in the viewport.)
plus_code (see
Open Location Code (https://en.wikipedia.org/wiki/Open_Location_Code)
and plus codes (https://plus.codes)) is an encoded
location reference, derived from
latitude and longitude coordinates, that
represents an area: 1/8000th of a degree by
1/8000th of a degree (about 14m x
14m at the equator) or smaller. 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).
The plus code is formatted as a global code and a compound code:
global_code is a 4 character area code and 6 character or longer local code

(849VCWC8+R9).
compound_code is a 6 character or longer local code with an explicit location

(CWC8+R9, Mountain View, CA, USA).
Typically, both the global code and compound code are returned. However, if
the
chevron_left
result is in a remote location (for example, an ocean or desert) only the
global code
may be returned.
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_id is a unique
identifier that can be used with other Google APIs. For example,
you can
use the place_id in a
Places API
(/maps/documentation/places/web-service/details) request to get
details of a local
business, such as phone number, opening hours, user
reviews, and more. See the
place ID
overview (/maps/documentation/places/web-service/place-id).
Address types and address component types
The types[] array in the result indicates the

address type. Examples of address types
include a street address, a
country, or a political entity. There is also a types[] array in
the
address_components[], indicating the type of each part of the
address. Examples include
street number or country. (Below is a full list of
types.) Addresses may have multiple types.
The types may be considered 'tags'.
For example, many cities are tagged with the
political and the
locality type.
The following types are supported and returned by the geocoder in both the
address type
and address component type arrays:
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.
chevron_left
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

level. This type indicates a minor civil division.
Not all nations exhibit these
administrative_area_level_4 indicates a fourth-order civil

administrative_area_level_5 indicates a fifth-order civil

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
plus_code indicates 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).
See https://plus.codes (https://plus.codes)
for details.
chevron_left
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 listed here. 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.
landmark indicates a nearby place that is used as a reference,

to aid navigation.
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.
The Geocoding API isn't guaranteed to return any

particular component for an address within our data set
e thought of as the city,
such as Brooklyn, may not show up as locality, but rather as another component -
sublocality_level_1. What specific components are returned is subject to change without notice.
Design yo
o be flexible if you are attempting to extract address components from the
response.
chevron_left
Viewport biasing
In a Geocoding request, you can instruct the Geocoding service to prefer

results within a
given viewport (expressed as a bounding box). You do so
within the request URL by setting
the bounds parameter. Note
that biasing only prefers results within the bounds; if more
relevant
results exist outside of these bounds, they may be included.
The bounds parameter defines the latitude/longitude coordinates

of the southwest and
northeast corners of this bounding box using a pipe
(|) character to separate the
coordinates.
For example, a geocode for "Winnetka" generally returns this suburb of

Chicago:
Request:
https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key= YOUR_A
Response:
{
"results" : [
{
{
"long_name" : "Winnetka",
"short_name" : "Winnetka",
},
{
"long_name" : "New Trier",
"short_name" : "New Trier",
},
{
"long_name" : "Cook County",
"short_name" : "Cook County",
},
{
"long_name" : "Illinois",
"short_name" : "IL",
"types" : [ "administrative_area_level_1",
chevron_left "political" ]
},
{
}
],
"formatted_address" : "Winnetka, IL, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 42.1282269,
"lng" : -87.7108162
},
"southwest" : {
"lat" : 42.0886089,
"lng" : -87.7708629
}
},
"location" : {
"lat" : 42.10808340000001,
"lng" : -87.735895
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 42.1282269,
"lng" : -87.7108162
},
"southwest" : {
"lat" : 42.0886089,
"lng" : -87.7708629
}
}
},
"place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
}
],
"status" : "OK"
}
However, adding a bounds argument defining a bounding box for

the San Fernando Valley of
Los Angeles results in this geocode returning the neighborhood
named "Winnetka" in that
location:
Request: chevron_left
https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.1
-118.604794|34.236144,-118.500938&key= YOUR_API_KEY
Response:
{
"results" : [
{
{
"long_name" : "Winnetka",
"short_name" : "Winnetka",
"types" : [ "neighborhood", "political" ]
},
{
"long_name" : "Los Angeles",
"short_name" : "LA",
},
{
"long_name" : "Los Angeles County",
"short_name" : "Los Angeles County",
},
{
"long_name" : "California",
"short_name" : "CA",
},
{
}
],
"formatted_address" : "Winnetka, Los Angeles, CA, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 34.2355209,
"lng" : -118.5534191
},
"southwest" : {
chevron_left
"lat" : 34.1854649,
"lng" : -118.588536
}
},
"location" : {
"lat" : 34.2048586,
"lng" : -118.5739621
},
"viewport" : {
"northeast" : {
"lat" : 34.2355209,
"lng" : -118.5534191
},
"southwest" : {
"lat" : 34.1854649,
"lng" : -118.588536
}
}
},
"place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
}
],
"status" : "OK"
}
Region biasing
In a Geocoding request, you can instruct the Geocoding service to return

results biased to a
particular region by using the region
parameter. This parameter takes a ccTLD
(https://en.wikipedia.org/wiki/CcTLD) (country code top-level
domain) argument specifying the
region bias. Most ccTLD codes are identical to
ISO 3166-1 codes, with some notable
exceptions. For example, the United
Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1
code is "gb"
(technically for the entity of "The United Kingdom of Great Britain and
Northern
Ireland").
Geocoding results can be biased for every domain in which the main
Google Maps
application is officially launched. 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 API is set to the United States. Request:
chevron_left
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key= YOUR_API
Response:
{
"results" : [
{
{
"long_name" : "Toledo",
"short_name" : "Toledo",
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
},
{
"long_name" : "Ohio",
"short_name" : "OH",
},
{
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
chevron_left
"lng" : -83.55521200000001
},
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
}
],
"status" : "OK"
}
A Geocoding request for "Toledo" with region=es (Spain) will

return the Spanish city.
Request:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key
Response:
{
"results" : [
{
{
"short_name" : "Toledo",
},
{
"short_name" : "TO",
},
{
"long_name" : "Castile-La Mancha",
"short_name" chevron_left
: "CM",

},
{
"long_name" : "Spain",
"short_name" : "ES",
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
}
],
"status" : "OK"
}
Component filtering
chevron_left
In a Geocoding response, the Geocoding API can return address

results restricted to a
specific area. You can specify the restriction using
the components filter. A filter consists of
a list of
component:value pairs separated by a pipe (|).
Filter values support the same
methods of spelling correction and partial
matching as other Geocoding requests. If the
geocoder finds a partial match for a
component filter, the response will contain a
partial_match field.
The components that can be filtered include:
postal_code matches postal_code

and postal_code_prefix.
country matches a country name or a two letter

ISO 3166-1
(https://en.wikipedia.org/wiki/ISO_3166-1)
country code. The API follows the ISO
standard for
defining countries, and the filtering works best when using the
corresponding ISO code of the country.
star Note: If you receive unexpected results with a country code, verify
that you are using a code which
includes the countries, dependent territories, and special
areas of geographical interest you
intend. You can find code information at
Wikipedia: List of ISO
3166 country codes
(https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) or the ISO Online Browsing
Platform (https://www.iso.org/obp/ui/#search).
The following components may be used to influence results, but will not be enforced:
route matches the long or short name of a route.
locality matches against locality and

sublocality types.
administrative_area matches all the

administrative_area levels.
Notes about component filtering:
Do not repeat these component filters in requests, or the API will return
Invalid_request: country, postal_code,
route
If the request contains repeated component filters, the API evaluates those
filters as
an AND, not an OR.
Results are consistent with Google Maps, which occasionally yields

unexpected
ZERO_RESULTS responses. Using Place Autocomplete
may provide better results in
some use cases. To learn more, see
this
FAQ
(/maps/documentation/geocoding/faq#trbl_component_filtering).
chevron_left
For each address component, either specify it in the address

parameter or in a
components filter, but not both. Specifying
the same values in both may result in
ZERO_RESULTS.
A geocode for "High St, Hastings" with components=country:GB

returns a result in
Hastings, England rather than in Hastings-On-Hudson, USA. Request:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&comp
&key= YOUR_API_KEY
Response:
{
"results" : [
{
{
"long_name" : "High Street",
"short_name" : "High St",
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
},
{
"long_name" : "England",
"short_name" : "England",
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
},
{
"long_name" : "TN34 3EY",
chevron_left
"short_name" : "TN34 3EY",
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
}
],
"status" : "OK"
}
A geocode request for the locality of "Santa Cruz" with

components=country:ES returns
Santa Cruz de Tenerife in
Canary Islands, Spain. Request:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+c
&key= YOUR_API_KEY
chevron_left
Response:
{
"results" : [
{
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
},
{
"long_name" : "Spain",
"short_name" : "ES",
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"viewport" : {
"northeast" : {
chevron_left
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
}
],
"status" : "OK"
}
onent filtering returns a ZERO_RESULTS response

only if you provide filters that exclude each other. Reques
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_a
&key= YOUR_API_KEY
Response:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
You can make valid queries without the address parameter, using the
components filter.
(When geocoding a full address,
the address parameter is required if the request contains
the
names and numbers of buildings.) Request:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|a
:Helsinki|country:Finland&key= YOUR_API_KEY
Response:
chevron_left
{
"results" : [
{
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
},
{
"long_name" : "Finland",
"short_name" : "FI",
},
{
"long_name" : "00101",
"short_name" : "00101",
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
}, chevron_left
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
}
],
"status" : "OK"
}
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 opposite,
translating a location on the map
into a human-readable address, is known as
reverse geocoding.
Required parameters in a reverse geocoding request:
latlng — The latitude and longitude

values specifying the location for which you wish
to obtain the closest,
human-readable address.

Optional parameters in a reverse geocoding request:
These are the optional parameters that you can include in a reverse
Geocoding request:
language — The language in which to return results.
See the list of supported

languages (/maps/faq#languagesupport). Google often
updates the supported languages, so this
list may not be exhaustive.
If language is not supplied, the geocoder attempts to

use the preferred
language as specified in the
Accept-Language header, or the native language of
the
domain from which the request is sent.
The geocoder 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
chevron_leftto 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 geocoder uses

the
closest match.
result_type — A filter of one or more address types,

separated by a pipe (|). If the
parameter contains multiple
address types, the API returns all addresses that match
any of the types.
A note about processing: The result_type parameter does not
restrict the search to the specified address type(s). Rather, the
result_type acts as a
post-search filter: the API fetches all
results for the specified latlng, then discards
those results
that do not match the specified address type(s).The following values are
supported:
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
administrative levels are states.
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
administrative levels are counties.
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
chevron_left
administrative_area_level_5 indicates a fifth-order civil

entity below the
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
plus_code indicates 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). See https://plus.codes (https://plus.codes)
for details.
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.

Typically, these "POI"s
are prominent local entities that don't easily fit
in another category, such as
"Empire State Building" or "Eiffel Tower".
location_type — A filter of one or more location types,

separated by a pipe (|). If the
parameter contains multiple
location types, the API returns all addresses that match
any of the types.
A note about processing: The location_type parameter does not
restrict the search to the specified location type(s). Rather, the
location_type acts
as a post-search filter: the API fetches all
results for the specified latlng, then
discards those results
that do not match the specified location type(s).
The following
values are supported:
chevron_left
"ROOFTOP" returns only the addresses for which Google

has location
information accurate down to street address precision.
"RANGE_INTERPOLATED" returns only the addresses that

reflect an
approximation (usually on a road) interpolated between two
precise points
(such as intersections). An interpolated range generally
indicates that rooftop
geocodes are unavailable for a street address.
"GEOMETRIC_CENTER" returns only geometric

centers of a location such as a
polyline (for example, a street) or
polygon (region).
"APPROXIMATE" returns only the addresses that are

characterized as
approximate.
If both result_type and location_type filters

are present then the API returns only those
results that match both the
result_type and the location_type values. If none
of the
filter values are acceptable, the API returns
ZERO_RESULTS.
Example of reverse geocoding
The following query contains the latitude/longitude value for a

location in Brooklyn:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&
Note: Ensure that no space exists between

the latitude and longitude values when passed
in the latlng
parameter.
The above query returns the following result:
{
"results" : [
{
{
"long_name" : "277",
},
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
chevron_left
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "sublocality", "political" ]
},
{
"long_name" : "Kings",
"short_name" : "Kings",
},
{
"long_name" : "New York",
"short_name" : "NY",
},
{
},
{
"long_name" : "11211",
"short_name" : "11211",
}
],
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.714232,
"lng" : -73.9612889
},
"viewport" : {
"northeast" : {
"lat" : 40.7155809802915,
"lng" : -73.9599399197085
},
"southwest" : {
"lat" : 40.7128830197085,
"lng" : -73.96263788029151
} chevron_left
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
},
... Additional results[] ...
Note that the reverse geocoder returned more than one result. The
"formatted_address"
results 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
denoted 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
any of
these types as valid results.
The reverse geocoder matches political entities (countries, provinces,

cities and
neighborhoods), street addresses, and postal codes.
The full list of formatted_address values returned by the

previous query is shown below.
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",

"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",
Generally, addresses are returned from most specific to least specific;

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 specific type of
address, see the section below on restricting
results by type. (#reverse-restricted)
Reverse geocoding is an estimate. The

geocoder will attempt to find the closest addressable location
with
n tolerance. If no match is found, the geocoder will
return zero results.
chevron_left
Reverse geocoding filtered by type
The following example filters the addresses returned to include only those
with a location
type of ROOFTOP and an address type of
street_address.
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key= YOUR_API_KEY
These filters are only valid for

reverse geocoding.
Reverse geocoding responses
The format of the reverse geocoding response is the same as the Geocoding
response. See
Geocoding responses (#GeocodingResponses).
Below are the status codes possible in a
reverse geocoding response.
Reverse geocoding status codes
The "status" field within the Geocoding response object contains

the status of the
request, and may contain debugging information to help you
track down why reverse
geocoding is not working. The "status"
field may contain the following values:
"OK" indicates that no errors occurred and at least one

address was returned.
"ZERO_RESULTS" indicates that the reverse geocoding was

successful but returned no
results. This may occur if the geocoder was
passed a latlng in a remote location.
"OVER_QUERY_LIMIT" indicates that you are over your

quota.
"REQUEST_DENIED" indicates that the request was denied.

Possibly because the
request includes a result_type or
location_type parameter but does not include
an API key.
"INVALID_REQUEST" generally indicates one of the following:
The query (address, components or

latlng) is missing.
An invalid result_type or location_type was

given.
"UNKNOWN_ERROR" indicates that the request could not be

processed due to a server
error. The request may succeed
chevron_left if you
try again.
Reverse geocoding plus codes
The plus_code field within the Geocoding response object

contains a plus code that best
approximates the queried latitude and longitude.
In addition the JSON results array will in
most cases contain a full Geocoding
result with a plus_code type and an address
containing a plus
code. The distance between the decoded plus code and the request point
is
guaranteed to be under 10 meters.
Retrieving an address for a Place ID
Required parameters:
place_id — The place ID of the place for which

you wish to obtain the human-
readable address. The place ID is a unique
identifier that can be used with other
Google APIs. For example, you can
use the placeID returned by the
Roads API
(/maps/documentation/roads/snap)
to get the address for a snapped point. For more
information about place
IDs, see the place ID overview
(/maps/documentation/places/web-service/place-id)..

The optional parameters are the same as those for

reverse geocoding (#ReverseGeocoding).
The following query contains the place ID of a place in Brooklyn:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFU
&key= YOUR_API_KEY
The above query returns the following result:
{
"results" : [
{
{
"long_name" : "277",
}, chevron_left
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "political", "sublocality", "sublocality_level_1"
},
{
"long_name" : "Kings County",
"short_name" : "Kings County",
},
{
"long_name" : "New York",
"short_name" : "NY",
},
{
},
{
"long_name" : "11211",
"short_name" : "11211",
}
],
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.7142205,
"lng" : -73.9612903
},
"viewport" : {
"northeast" : {
"lat" : 40.71556948029149,
"lng" : -73.95994131970849
}, chevron_left
"southwest" : {
"lat" : 40.7128715197085,
"lng" : -73.9626392802915
}
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
}
],
"status" : "OK"
}
For a description of the fields in the response, see Geocoding

responses
(#GeocodingResponses).
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0
License (https://creativecommons.org/licenses/by/4.0/), and code samples are licensed under the Apache
2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site
Policies (https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its
affiliates.
Last updated 2021-09-14 UTC.
chevron_left

What Is Geocoding?: Geocoding Is The Process of Converting Addresses (Like "1600 Amphitheatre Parkway

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

What Is Geocoding?: Geocoding Is The Process of Converting Addresses (Like "1600 Amphitheatre Parkway

Uploaded by

Copyright:

Available Formats

15/09/2021, 06:53 Overview

| Geocoding API | Google Developers

ervice is also available as part of the client-side

Geocoding is the process of converting addresses (like

Reverse geocoding (#ReverseGeocoding) is the

The Geocoding API provides a direct way to access these services

Enter a query to geocode, or click on the map to reverse geocode.

View this example

Before you begin

Note: This service is generally designed for geocoding

Geocoding API request format

A Geocoding API request takes the following form:

where outputFormat may be either of the following values:

json (recommended) indicates output in JavaScript Object

xml indicates output in XML

HTTPS is required for requests that use an API key.

Note: URLs must be

your URLs. Note that different browsers,

The rest of this page describes geocoding (#geocoding) and

Geocoding (latitude/longitude lookup)

erved characters (for example the plus sign "+") must be

Required parameters in a geocoding request:

address — The street address or plus code (https://plus.codes)

global code is a 4 character area code and 6 character or longer

compound code is a 6 character or longer local code with an

components — A components filter with elements

key — Your application's API key. This key identifies

Please refer to the FAQ (/maps/faq#geocoder_queryformat) for

Optional parameters in a Geocoding request:

bounds — The bounding box of the viewport

language — The language in which to

See the list of supported

If language is not supplied, the geocoder attempts to

The geocoder does its best to provide a street address that is

If a name is not available in the preferred language, the geocoder uses

region — The region code, specified as a ccTLD

components — A components filter with elements

Geocoding responses are returned in the format indicated by the

In this example, the Geocoding API requests a json response for

This request demonstrates using the JSON output flag:

This request demonstrates using the XML output flag:

Note that the JSON response contains two root elements:

"status" contains metadata on the request. See

"results" contains an array of geocoded address information and

Generally, only one entry in the "results" array is returned for

OVER_DAILY_LIMIT indicates any of the following:

The API key is missing or invalid.

Billing has not been enabled on your account.

A self-imposed usage cap has been exceeded.

The provided method of payment is no longer valid (for example, a

See the Maps FAQ (/maps/faq#over-limit-key-error) to learn

"REQUEST_DENIED" indicates that your request was denied.

"INVALID_REQUEST" generally indicates that the query (address,

"UNKNOWN_ERROR" indicates that the request could not be

This field is not guaranteed to be always present, and its

A typical result contains the following fields:

The types[] array indicates the type of the returned

formatted_address is a string containing the human-readable

The formatted address is logically composed of one or more address

Do not parse the formattedchevron_left

formatted address field.

address_components[] is an array containing the separate

Each address component typically contains the following fields: