PrintThe ability to geocode addresses in V3 of the API is provided by the Geocoder class. This class appears to make use of the same geocoding engine that is utilized on Google's own maps.google.com page. The same variety of strings that can be entered in the search box on Google's site can also be passed to the geocoder (e.g., full addresses, city/state combinations, and zip codes all yield matches).
Addresses are passed to the geocoder by creating a GeocoderRequest object as an object literal. In addition to the address, the GeocoderRequest class also makes it possible to specify where to search (as a bounding box or within a country) and the preferred language for the results.
The API samples page provides a very good example of geocoding. Go to that page, test its behavior, then view its source so you can follow along with my description of how the page works.
In the HTML <body> section is a <div> element containing two <input> elements. The first input element (the search box) has its type set to textbox and its initial value to Sydney, NSW. The second input element is of the button type and has its onclick attribute set to a function called codeAddress().
Moving up to the JavaScript, note that the Geocoder object is created before the two functions, making it possible to work with the object in either function through the global variable geocoder
That brings us to the codeAddress() function that gets executed in response to clicks on the Geocode button. Logically, the first step in this function is to obtain the user's entry in the search box using the DOM. This address is passed along as an object literal in a call to the Geocoder object's geocode() method. The second argument passed to the method is a callback function that handles the matches that are returned when the geocoding is complete. Within the callback function, the success/failure of the request is accessible through the status variable and, assuming the request returns one or more matches, those matches are accessible through the results variable.
Before processing the results though, the function first checks to make sure the request was successful by examining the status code and looking for a value of OK. (Here is the full list of codes.) If the status variable holds something other than OK, that value is reported through an alert() box.
The geocoding results are returned as an array of GeocoderResult objects defined in JavaScript Object Notation (JSON) format. JSON is a commonly used method for exchanging data across networks and follows the same basic syntax you've used to define object literals throughout the course. A GeocoderResult object has a geometry property that returns an object of the GeocoderGeometry type. That object, in turn, has a location property that returns a LatLng object (a point). The expression results[0].geometry.location returns the position of the first match in the array of GeocoderResults. That position is used to set the map's center and to add a plain marker. If you were writing your own geocoding application, you might want to examine all the matches in the array using a loop instead of retrieving just the first match.
Note
The accuracy of each matching point can be found using results[0].geometry.location_type. The location type codes are detailed in the API Reference.