Geocoding with the Google Geocoder

Before using the Google Geocoder, you must have a Google Maps API key. It will not work without one. If you don’t yet have one, get yours via the Google Maps API page. Also, to get this out of the way, Google has provided a fantastic service free of charge for non-commercial purposes. Please respect their terms of service.

Download the free Google Geocoder

The Google Geocoder is very similar to the Quick ‘n Dirty Geocoder. It is free software, and can be used and distributed however you like. It installs in a servlet container, and accesses the Google Maps web service to translate the names and addresses you supply (in a text file) into geographic coordinates, which it then writes back to your PC and/or a database.

For details on how to install and use this software, frequently asked questions, configuration, etc., refer to the wiki article. The short version is just drop goog.war into Tomcat’s webapps directory, start it, then follow the instructions at http://localhost:8080/goog/code. This post describes some of the Java code used to implement the communication between the Google geocoder and the Google Maps web service.

The big difference between this and the Q&D Geocoder is that this retrieves an XML file rather than a CSV file. Google does a great job at parsing the address information you submit, and they send it back to you in a standardized form. This is great if, for example, you have many differnet people typing or submitting street addresses, and they each use different abbreviations or differing levels of detail in their addresses. Google takes all of the work out of making sure those addresses are stored in a common, standard format.

JDOM is used here to parse the returned XML, so the first step is to build a JDOM Document, which is done by passing the InputStream to a SAXBuilder.

public Document toJDOM(String wsUrl) {
try {
URL url = new URL(wsUrl);
SAXBuilder builder = new SAXBuilder();
return builder.build(url.openStream());
} catch(IOException ex) {
return null;
} catch(JDOMException ex) {
return null;
}
}

Then you can extract the bits you need. I usually start with a return code: 200 indicates a good return; 601 indicates an incomplete address was entered; 602 indicates an unknown address; 603 indicates an address Google is not permitted to show (Groom Lake?); and 620 indicates that the request was throttled. After a return code, JDOM is used to extract the standardized address.

Document results = this.toJDOM(url.toString());
int returnCode = geocodeReturnCode(results);

if(returnCode == 200) {
double[] coords = extractCoordinates(results);
if(areValid(coords)) {
String[] addressParts = addressToStringArray(extractNormalizedAddress(results));
//snip: set Place properties
}
}

public String extractNormalizedAddress(Document doc) {
Element e = doc.getRootElement();
Namespace ns = e.getNamespace();

Element address = e.getChild(”Response”, ns).getChild(”Placemark”, ns).getChild(”address”, ns);
if(address != null) {
return address.getText();
}
return null;
}

Notes

• The Google Geocoder will not send requests faster than one per second. Even at one per second, you may get the occasional 602 620 error code. I saw it about once every 100 queries.
• I got a roughly 98 percent success rate on geocoding.

Learn More & Download the Google Geocoder (Swirl Wiki) | Read the Quick ‘n Dirty Geocoder post