google maps Geocoding Service

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*) — The LatLng for which you wish to obtain the closest, human-readable address.
bounds (optional) — The LatLngBounds within which to bias geocode results more prominently. (For more information see Viewport Biasing below.)
region (optional) — 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. (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 GeocoderResultsobject 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:
- 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 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 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.

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-existent address or a latng 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 or latLng) 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=" 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