google maps Geocoding Service
2012-10-09 00:17 youxin 阅读(633) 评论(0) 编辑 收藏 举报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 provides a geocoder class for geocoding addresses dynamically from user input. These requests are rate-limited to discourage abuse of the service. If instead, you wish to geocode static, known addresses, see the Geocoding web service documentation.
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
object. The Geocoder.geocode()
method initiates a request to the geocoding service, passing it a GeocodeRequest
object literal containing the input terms and a callback method to execute upon receipt of the response.
The GeocodeRequest
object literal contains the following fields:
{
address: string,
latLng: LatLng,
bounds: LatLngBounds,
region: string
}
These fields are explained below.
address
(required*) — The address which you want to geocode.latLng
(required*) — TheLatLng
for which you wish to obtain the closest, human-readable address.bounds
(optional) — TheLatLngBounds
within which to bias geocode results more prominently. (For more information see Viewport Biasing below.)region
(optional) — The region code, specified as a IANA languageregion
subtag. In most cases, these tags map directly to familiar ccTLD ("top-level domain") two-character values. (For more information see Region Code Biasing below.)
* Note: You may pass either an address
or a latLng
to lookup. (If you pass a latLng
, the geocoder performs what is known as a reverse geocode. See Reverse Geocoding for more information.)
The bounds
and region
parameters will only influence, not fully restrict, results from the geocoder.
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. Since the Geocoder may return more than one entry, the GeocoderResults
object literal is an array.
Geocoding Results
The GeocoderResults
object literal represents a single Geocoding result and is an object of the following form:
results[]: {
types[]: string,
formatted_address: string,
address_components[]: {
short_name: string,
long_name: string,
types[]: string
},
geometry: {
location: LatLng,
location_type: GeocoderLocationType
viewport: LatLngBounds,
bounds: LatLngBounds
}
}
These fields are explained below:
types[]
is an array indicating the type of the returned result. This array contains a set of one 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," which sometimes differs from country to country. (Note that some countries, such as Great Britain, do not allow distribution of true postal addresses due to licensing restrictions.) This address is generally composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" contains separate address components for "111 8th Avenue" (a street address), "New York" (the city) and "NY" (the US state). These address components are noted below. (For more information on types, see Typesbelow.address_component[]
is an array containing the separate address components, as explained above.-
geometry
contains the following information:location
contains the geocoded latitude,longitude value. Note that we return this location as aLatLng
object, not as a formatted string.location_type
stores additional data about the specified location. The following values are currently supported:google.maps.GeocoderLocationType.ROOFTOP
indicates that the returned result reflects a precise geocode.google.maps.GeocoderLocationType.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.google.maps.GeocoderLocationType.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).google.maps.GeocoderLocationType.APPROXIMATE
indicates that the returned result is approximate.
viewport
stores the recommended viewport for the returned result.bounds
(optionally returned) stores theLatLngBounds
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 Component Types
The types[]
array within the returned result indicates the address type. These types may also be returned within address_components[]
arrays to indicate the type of the particular address component. Addresses within 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 HTTP Geocoder:
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.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.colloquial_area
indicates a commonly-used alternative name for the entity.locality
indicates an incorporated city or town political entity.sublocality
indicates an first-order civil entity below a locality.neighborhood
indicates a named neighborhood.premise
indicates a named location, usually a building or collection of buildings with a common namesubpremise
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.
In addition to the above, address components may exhibit the following types:
post_box
indicates a specific postal box.street_number
indicates the precise street number.floor
indicates the floor of a building address.room
indicates the room of a building address.
Status Codes
The status
code may return one of the following values:
google.maps.GeocoderStatus.OK
indicates that the geocode was successful.google.maps.GeocoderStatus.ZERO_RESULTS
indicates that the geocode was successful but returned no results. This may occur if the geocode was passed a non-existentaddress
or alatng
in a remote location.google.maps.GeocoderStatus.OVER_QUERY_LIMIT
indicates that you are over your quota.google.maps.GeocoderStatus.REQUEST_DENIED
indicates that your request was denied for some reason.google.maps.GeocoderStatus.INVALID_REQUEST
generally indicates that the query (address
orlatLng
) is missing.
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.
var geocoder; var map; function initialize() { geocoder = new google.maps.Geocoder(); var latlng = new google.maps.LatLng(-34.397, 150.644); var mapOptions = { zoom: 8, center: latlng, mapTypeId: google.maps.MapTypeId.ROADMAP } map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions); } function codeAddress() { var address = document.getElementById("address").value; geocoder.geocode( { 'address': address}, function(results, status) { if (status == google.maps.GeocoderStatus.OK) { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location }); } else { alert("Geocode was not successful for the following reason: " + status); } }); } <body onload="initialize()"> <div id="map_canvas" style="width: 320px; height: 480px;"></div> <div> <input id="address" type="textbox" value="Sydney, NSW"> <input type="button" value="Encode" onclick="codeAddress()"> </div> </body>
View example (geocoding-simple.html)
via:https://developers.google.com/maps/documentation/javascript/geocoding