Includes enterprise licensing and support
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. The Google Maps API Geocoding Service provides a direct way to access a geocoder via an HTTP request.
Note: the geocoding service may only be used in conjunction with displaying results on a Google map; geocoding results without displaying them on a map is prohibited. For complete details on allowed usage, consult the Maps API Terms of Service License Restrictions.
This service is designed for geocoding static (known) addresses using a REST interface, for placement of application content on a map. For dynamic geocoding of user-defined addresses (for example, within a user interface element), consult the documentation for the JavaScript Client Geocoder or the Maps API for Flash Client Geocoder.
Geocoding is a time and resource intensive task. Whenever possible, pre-geocode known addresses (using the Geocoding Service described here or another geocoding service), and store your results in a temporary cache of your own design.
You may access the Google Maps API Geocoding Service directly over HTTP. To access the geocoder, send a request to http://maps.google.com/maps/geo? with the following parameters in the URL:
|
q (required) — The address that you want to geocode. Note
that this address must be encoded in UTF-8.*key (required) — Your API key.sensor (required) — Indicates whether or not the geocoding request comes
from a device with a location sensor. This value must be either true or false.
(Note that devices with sensors generally perform their own geocoding by definition; therefore,
most geocoding requests to the Maps API Geocoding service should set sensor to false.)output (required) — The format in which the output should be generated.
The options are xml, kml, csv, or (default) json.
(For more information, see Geocoding Responses below.)ll (optional) — The {latitude,longitude} of the viewport center
expressed as a comma-separated string (e.g. "ll=40.479581,-117.773438" ). This parameter
only has meaning if the spn parameter is also passed to the geocoder.
(For more information see Viewport Biasing below.)spn (optional) — The "span" of the viewport expressed as a
comma-separated string of {latitude,longitude} (e.g. "spn=11.1873,22.5" ). This parameter
only has meaning if the ll parameter is also passed to the
geocoder. (For more information see Viewport Biasing below.)gl (optional) — The country code, specified as a ccTLD
("top-level domain") two-character value. (For more information see
Country Code Biasing below.)Note: The gl and spn,ll viewport parameters will
only influence, not fully restrict, results from the geocoder.
* Note that if you supply a textual latitude/longitude value in the
q parameter, this query initiates a reverse geocode. For more information, see
Reverse Geocoding below.
In this example, we request the geographic coordinates of Google's headquarters:
http://maps.google.com/maps/geo?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&output=json&sensor=true_or_false&key=your_api_key
We've left the sensor parameter in this example as a variable true_or_false
to emphasize that you must set this value to either true or
false explicitly.
The output parameter specifies the format of the response from the
Geocoding Service. Each output has a slightly different format, though
most share common structure and element names. The following values for output
are supported:
json (default) — The response is formatted as a JSON object. This format
is preferred as it is generally more compact.kml — The response is returned as KML with a kml MIME type.xml — The response is returned as KML with an xml MIME type.csv — The response is returned as a comma-seperated value,
described below.In this example, the Geocoding Service returns the following response for a query on "1600 amphitheatre mountain view ca" when requesting JSON. (Note that actual JSON may contain less whitespace.)
{
"name": "1600 Amphitheatre Parkway, Mountain View, CA",
"Status": {
"code": 200,
"request": "geocode"
},
"Placemark": [ {
"id": "p1",
"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"AddressDetails": {
"Country":{
"CountryNameCode": "US",
"CountryName": "USA",
"AdministrativeArea":{
"AdministrativeAreaName": "CA",
"Locality":{
"LocalityName": "Mountain View",
"Thoroughfare":{
"ThoroughfareName": "1600 Amphitheatre Pkwy"
},
"PostalCode":{
"PostalCodeNumber": "94043"
}
}
}
},
"Accuracy": 8
},
"Point": {
"coordinates": [ -122.0841430, 37.4219720, 0 ]
}
} ]
}
Note: Results are always encoded in UTF-8.
Note that the JSON response contains three root elements:
"name" contains the original query."Status" contains metadata on the request. See Status Codes below."Placemark" contains address information of the geocoded result.Generally, only one "Placemark" is returned, though the geocoder may return
several results when address queries are ambiguous.
If you wish, you may also retrieve geocoding responses in XML or KML. Both outputs
retrieve identical structured data except that their MIME types are set to kml
or xml. If you request a geocode and specify an output as KML, for example,
the geocoding response may launch Google Earth to display to the result.
The equivalent response to the above example as KML is shown below.
<kml xmlns="http://earth.google.com/kml/2.0">
<Response>
<name>1600 amphitheatre mountain view ca</name>
<Status>
<code>200</code>
<request>geocode</request>
</Status>
<Placemark>
<address>
1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
</address>
<AddressDetails Accuracy="8">
<Country>
<CountryNameCode>US</CountryNameCode>
<AdministrativeArea>
<AdministrativeAreaName>CA</AdministrativeAreaName>
<SubAdministrativeArea>
<SubAdministrativeAreaName>Santa Clara</SubAdministrativeAreaName>
<Locality>
<LocalityName>Mountain View</LocalityName>
<Thoroughfare>
<ThoroughfareName>1600 Amphitheatre Pkwy</ThoroughfareName>
</Thoroughfare>
<PostalCode>
<PostalCodeNumber>94043</PostalCodeNumber>
</PostalCode>
</Locality>
</SubAdministrativeArea>
</AdministrativeArea>
</Country>
</AddressDetails>
<Point>
<coordinates>-122.083739,37.423021,0</coordinates>
</Point>
</Placemark>
</Response>
</kml>
Note that the KML response is structurally identical to the JSON output.
If you prefer a shorter response that is easier to parse and don't need
special features such as structured data, the Geocoding Service also
provides a csv output. A reply returned in the csv
format consists of four numbers, separated by commas:
The following examples show replies for three addresses, in increasing order of accuracy: "State St, Troy, NY", "2nd st & State St, Troy, NY" and "7 State St, Troy, NY"
200,6,42.730070,-73.690570 200,7,42.730210,-73.691800 200,8,42.730287,-73.692511
| Code | Equivalent GGeoStatusCode | Description |
|---|---|---|
| 200 | G_GEO_SUCCESS |
No errors occurred; the address was successfully parsed and its geocode was returned. |
| 500 | G_GEO_SERVER_ERROR |
A geocoding or directions request could not be successfully processed, yet the exact reason for the failure is unknown. |
| 601 | G_GEO_MISSING_QUERY |
An empty address was specified in the HTTP q parameter.
|
| 602 | G_GEO_UNKNOWN_ADDRESS |
No corresponding geographic location could be found for the specified address, possibly because the address is relatively new, or because it may be incorrect. |
| 603 | G_GEO_UNAVAILABLE_ADDRESS |
The geocode for the given address or the route for the given directions query cannot be returned due to legal or contractual reasons. |
| 610 | G_GEO_BAD_KEY |
The given key is either invalid or does not match the domain for which it was given. |
| 620 | G_GEO_TOO_MANY_QUERIES |
The given key has gone over the requests limit in the 24 hour period or has submitted too many requests in too short a period of time. If you're sending multiple requests in parallel or in a tight loop, use a timer or pause in your code to make sure you don't send the requests too quickly. |
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.
The HTTP Geocoder supports reverse geocoding directly using the
q parameter. Instead of supplying a textual address as the query
parameter, supply a comma-separated latitude/longitude
pair. For example, the following query contains the latitude/longitude value
for a location in Brooklyn:
http://maps.google.com/maps/geo?q=40.714224,-73.961452&output=json&sensor=true_or_false&key=your_api_key
Note: Ensure that no space exists between
the latitude and longitude values when passed in the q
parameter.
This query returns the following result:
{
"name": "40.714224,-73.961452",
"Status": {
"code": 200,
"request": "geocode"
},
"Placemark": [ {
"id": "p1",
"address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
"AddressDetails": {
"Country": {
"CountryNameCode": "US",
"CountryName": "USA",
"AdministrativeArea": {
"AdministrativeAreaName": "NY",
"Locality": {
"LocalityName": "Brooklyn",
"Thoroughfare":{
"ThoroughfareName": "275-291 Bedford Ave"
},
"PostalCode": {
"PostalCodeNumber": "11211"
}
}
}
},
"Accuracy": 8
},
"Point": {
"coordinates": [ -73.9614669, 40.7142298, 0 ]
}
}
// Additional Placemarks ...
Note that the reverse geocoder returned more than one result, with each
result tagged with a sequential "id" ("p1","p2",etc.). Geocoding
"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.
The reverse geocoder matches political entities (countries, provinces, cities and neighborhoods), street addresses, and postal codes.
The full list of addresses returned by the previous query are shown below.
"address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA", "address": "Williamsburg, NY, USA", "address": "New York 11211, USA", "address": "Kings, New York, USA", "address": "Brooklyn, New York, USA", "address": "New York, New York, USA", "address": "New York, USA", "address": "United States"
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 Accuracy field of the returned
Placemarks. (See Geocoding
Accuracy below.)
Note: Reverse geocoding is not an exact
science. The geocoder will attempt to find the closest addressable location
within a certain tolerance; if no match is found, the geocoder will usually
return a G_GEO_UNKNOWN_ADDRESS (602) status code.
You can also 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 two values: ll and spn, which together define
this bounding box.
The ll parameter defines the latitude/longitude coordinates of the center
of this bounding box, while the spn parameter defines the latitude/longitude
"span" of this bounding box in both vertical and horizontal dimensions.
For example, a geocode for "Winnetka" generally returns this suburb of Chicago:
http://maps.google.com/maps/geo?q=Winnetka&output=json&sensor=false&key=your_key_here
#
# Returns
#
{
"name": "Winnetka",
"Status": {
"code": 200,
"request": "geocode"
},
"Placemark": [ {
"id": "p1",
"address": "Winnetka, IL, USA",
"AddressDetails": {"Country": {"CountryNameCode": "US","CountryName": "USA","AdministrativeArea": {"AdministrativeAreaName": "IL","Locality": {"LocalityName": "Winnetka"}}},"Accuracy": 4},
"Point": {
"coordinates": [ -87.7417070, 42.1083080, 0 ]
}
} ]
}
However, adding ll and spn arguments defining a bounding box for
the San Fernando Valley of Los Angeles results in this geocode returning the neighborhood
named "Winnetka" in that location:
http://maps.google.com/maps/geo?q=Winnetka&output=json&sensor=false&key=your_api_key&ll=34.197605,-118.546944&spn=0.247048,0.294914
#
# Returns:
#
{
"name": "Winnetka",
"Status": {
"code": 200,
"request": "geocode"
},
"Placemark": [ {
"id": "p1",
"address": "Winnetka, California, USA",
"AddressDetails": {"Country": {"CountryNameCode": "US","CountryName": "USA","AdministrativeArea": {"AdministrativeAreaName": "CA","AddressLine":Winnetka}},"Accuracy": 4},
"Point": {
"coordinates": [ -118.5710220, 34.2131710, 0 ]
}
} ]
}
The Google Maps API Geocoding Service returns address results influenced by the domain (country) from which the request is sent. For example, searches for "San Francisco" may return different results if sent from a domain within the United States than one sent from Spain.
You can also set the Geocoding Service to return results biased to a
particular country using the gl parameter. This parameter
takes a ccTLD (county code
top-level domain) argument specifying the country bias. Most ccTLD codes are
identical to ISO 3166-1 codes, with some notable exceptions. For example,
Great Britain's ccTLD is "uk" (.co.uk) while its ISO 3166-1
code is "GB."
Geocoding requests can be sent for every domain in which the main Google Maps application offers geocoding.
For example, a geocode for "Toldeo" returns this result, as the default domain for the Geocoding Service is set to the United States:
http://maps.google.com/maps/geo?q=Toledo&output=json&sensor=false
# Returns:
#
{
"name": "Toledo",
"Status": {
"code": 200,
"request": "geocode"
},
"Placemark": [ {
"id": "p1",
"address": "Toledo, OH, USA",
"AddressDetails": {"Country": {"CountryNameCode": "US","CountryName": "USA","AdministrativeArea": {"AdministrativeAreaName": "OH","Locality": {"LocalityName": "Toledo"}}},"Accuracy": 4},
"Point": {
"coordinates": [ -83.5777820, 41.6529200, 0 ]
}
} ]
}
A geocode for "Toledo" with gl=es (Spain) will return the Spanish city:
http://maps.google.com/maps/geo?q=Toledo&output=json&sensor=false&gl=es
#
# Returns
#
{
"name": "Toledo",
"Status": {
"code": 200,
"request": "geocode"
},
"Placemark": [ {
"id": "p1",
"address": "Toledo, Spain",
"AddressDetails": {"Country": {"CountryNameCode": "ES","CountryName": "Spain","AdministrativeArea": {"AdministrativeAreaName": "CM","SubAdministrativeArea": {"SubAdministrativeAreaName": "Toledo","Locality": {"LocalityName": "Toledo"}}}},"Accuracy": 4},
"Point": {
"coordinates": [ -4.0244759, 39.8567775, 0 ]
}
} ]
}
The Google Maps API Geocoding Service returns an Accuracy value
within each returned Placemark.
This value indicates the resolution of the given result, but not necessarily
the correctness
of the result. For example, a geocode of "111 8th Avenue, New York, NY" may return
8 (Address) level accuracy, indicating that the geocode is on the
order of resolution of a street address. A geocode for "France" would only return
1 (Country) level accuracy.
The following table lists the geocoding accuracy values returned by the Geocoding Service. Note that these accuracy values only indicate the expected resolution. They do not indicate the confidence level of the geocode.
| Accuracy Value | Description |
|---|---|
0 |
Unknown accuracy. |
1 |
Country level accuracy. |
2 |
Region (state, province, prefecture, etc.) level accuracy. |
3 |
Sub-region (county, municipality, etc.) level accuracy. |
4 |
Town (city, village) level accuracy. |
5 |
Post code (zip code) level accuracy. |
6 |
Street level accuracy. |
7 |
Intersection level accuracy. |
8 |
Address level accuracy. |
9 |
Premise (building name, property name, shopping center, etc.) level accuracy. |