When the Google Maps API was released in early 2005, one of the notable omissions was the ability to geocode addresses.  This posed more of an inconvenience that anything else as there are many geocoding API’s available from various sources, some of which are free to use.  In addition, clever application developers quickly found a Google Maps hack that would simulate geocoding functionality through Google Maps.  However, the lack of true geocoding functionality built into the API was a bit of hindrance.  Earlier this month that all changed as Google added geocoding functionality to it’s Maps API in the form of a GClientGeocoder object which allows you to submit addresses for geocoding via JavaScript.  This functionality can also be accessed via HTTP requests directly from a client browser.  Some nice features of the geocoding functionality include:

- No need to break up the address into street components such as street name, city, country.  The address can be submitted as a single string.
- No need to worry about capitalization or punctuation
- Geocoder returns a nicely formatted version of the address you sent
- Geocoder returns the address broken up into components like street, country, province, prefecture, postal code, etc.
- Simpler version that returns a GLatLng
- Built-in cache to make the user experience faster response times on commonly used addresses
- Street level geocoding for the U.S., Canada, France, Germany, Italy, Spain, and Japan

At this time you are limited to 50,000 geocode requests per day per API key.  According to Google if you have a fairly stable database of addresses (e.g. a list of properties for sale), it is recommended that you geocode them once using the HTTP request method and cache the coordinates in your own database. This means your site will be faster for your users and also uses up less of your daily quota of geocode requests. 

GClientGeocoder
Let’s focus on the functionality provided by the GClientGeocoder object. 

An instance of GClientGeocoder can be created with the following line of code:

This instance of a geocoder talks directly to Google servers to fulfill geocoding requests.  An optional cache parameter allows you to specify a custom client-side cache of known addresses.  GClientGeocoder has two methods that can be used to send an address to Google for geocoding: getLatLng( ) and getLocations( ).

The getLatLng( ) method sends a request to the Google servers to geocode the specified address.  If the address is successfully located, the user-specified callback function is invoked with a GLatLng point. Otherwise, the callback function is given a null point. In the case of an ambiguous address, only the point for the best match is passed to the callback function.  Take a look at the code example below for more information on how to call getlatLng( ).  In this example, we geocode an address, add a marker at that point, and open an info window displaying the address.

The getLocations( ) method also sends a request to Google to geocode a specified address.  However, getLocations( ) differs in that it returns a JSON object containing a status code and one or more Placemark objects.  The status code is a response indicating whether the geocode request was successful or not.  Here is a full listing of the status codes obtained from the Google documentation:

In addition to the status code, one or more Placemark objects are returned.  Multiple Placemark objects are returned in the event that the geocoder finds more than one match.  Each Placemark object is composed of an address (nicely formatted and capitalized), AddressDetails, and a Point representing the location of the geocoded address.  For an example of a typical JSON object returned by the getLocations( ) method as well as a code example please see the Google documentation.
Caching Geocodes with GGeocodeCache
Performance of the geocoder can be improved through the use of the caching functionality built into GClientGeocoder.  This cache stores geocoded responses so that if the same address is geocoded again, the response will be returned from the cache rather than the Google geocoder.  This improves the performance of your application and lessens the number of requests sent to the geocoding service.  By default, caching is enabled, but can be turned off by passing a null value to the setCache( ) method on GClientGeocoder.  Caching is controlled through the GGeocodeCache class.  A new instance of GGeocodeCache is created through the GGeocodeCache( ) constructor which immediately call the reset( ) method to empty the cache.  Addresses can then be placed into the cache with the put( address,reply) method which stores the given reply under the given address.  Addresses can be retrieved from the cache through the get(address) method which returns the reply stored under the given address.  As we mentioned, the reset( ) method purges all addresses from the current cache.

One of the useful aspects of caching functionality is the ability to pre-build a cache to account for commonly used addresses in an application.  For example, if you have an application that displays common tourist attractions you would want to pre-build a client cache containing the geocoded address for each of the attractions.  This would remove the need to continually query the Google geocoder for the point of interest.
HTTP Geocoding Requests
In addition to the GClientGeocoder object you can also access the Maps API geocoder functionality through HTTP requests.  Combined with the XmlHttpRequest AJAX object, this gives you the ability to send geocode requests through server-side scripting.  A request should be sent to http://maps.google.com/maps/geo? with the following parameters:
- q - The address that you want to geocode
- key – Your Google Maps API key
- output – The format option (xml, kml, json)

For example:

http://maps.google.com/maps/geo?q=21734+Longwood,+San+Antonio+TX&output=xml&key=ABQIAAAA7_kD1t_m22HBF9feCaDPZxQZuc26M5nLyzIhAY0gIOH-LGKPdxQ6r3IzloZck1JnK6eAB02QGYg4Tg
In this case, we have specified a return type of “xml” which returns an XML output.  Open a web browser and paste the code above into the address bar and hit the “Enter” key to see the XML output returned by an HTTP request to the geocoder.  It should look something like what you see in the figure below.

Conclusion

According to Google, geocoding functionality was the most requested feature by developers.  This should come as no surprise since most applications built with the Google Maps API rely on placing points of interest on a map.  The recent update of the API to include geocoding functionality is a big step forward in the evolution of this already popular web mapping toolkit. 

Author Information

Mr. Pimpler is the owner of Geospatial Training Services, LLC, a provider of virtual and instructor led GIS training opportunities and the author of its popular virtual training course “Google Maps For Your Apps!” and the new PDF book “Google Maps API: The New World of Web Mapping”.  For more information on the Google Maps API or any other training opportunity provided by GeoSpatial Training Services, please visit our website at http://www.geospatialtraining.com

Looking for more gmaps tutorials? See Also: