Before using this API, you should understand that this API will call into Google's geocoding web service to do most of its heavy liftings. To use this geocoding web service, you need sign-up for an API key at http://www.google.com/apis/maps/signup.html . The process will take about 10 seconds. Read the service's terms and services and documentation, and note that there is a geocoding speed limit.
(from http://googlemapsapi.blogspot.com/2007/09/coming-soon-ip-based-geocode-limiting.html):
"In the coming week, the Maps API geocode limit will change from a key-based system to an IP-based system, with a new limit of 15,000 queries per day. If you're a developer with a website that's using client-side geocoding via the GClientGeocoder object, this change means that each of your website visitors will now be subject to their own 15K quota. However, if you're a developer using the HTTP geocoder, this change means that all the geocodes from your script will be subject to the same 15K quota (your web server will send the same IP to us with each geocode). We've made this change in our geocoder due to the number of developers who've had issues with the GClientGeocoder and going over quota in times of high mashup user volume."
That means if you run at a rate faster than the equivalent of 15000 requests per day (5.769 seconds per request estimated ) per IP address for several minutes, then Google will block you for a day. The standardizer API automatically enforces this limit by only sending out request in 5.769 second interval .
Once you have the api key, add the jar file to your project's classpath, then you can standardize any address with a few lines of codes.
Assuming that the API key is "AABBCC" and you would to standardize address "1600 Amphitheatre Parkway, Mountain View, CA" .
Since version 1.4, the standardizer is able to support multiple returned geocoded addresses. You are encouraged to use the standardization methods that return a list of addresse objects instead of the ones that return only one address object unless you are either, 1. sure that the input address can be geocoded to ONLY one address, or 2. no matter how many geocoded addresses were return, you want to always take the first one in the list.
For example, given the input address string "1600 Amphitheater, us" (tested on 11/18/2007), Google's geocoding service will return 10 addresses. You should examine each of them to determine which address to use is the best standardization of the input. From the limited test cases I had run, the first one in the list is not necessary the best match of the input.
GeoAddressStandardizer st = new GeoAddressStandardizer("AABBCC");
List<GeoAddress> addr = st.standardizeToGeoAddress("1600 Amphitheatre Parkway, Mountain View, CA");
If you are only standardizing US addresses, you write:
List<GeoUsAddress> addr = st.standardizeToGeoUsAddress("1600 Amphitheatre Parkway, Mountain View, CA");
GeoAddressStandardizer st = new GeoAddressStandardizer("AABBCC");
GeoAddress addr = st.standardizeToGeoAddress("1600 Amphitheatre Parkway, Mountain View, CA");
If you are only standardizing US addresses, you write:
GeoUsAddress addr = st.standardizeToGeoUsAddress("1600 Amphitheatre Parkway, Mountain View, CA");
The standardizer will convert the input address to a standardize format, even when the input address is in complete. For example:
GeoUsAddress addr = st.standardizeToGeoUsAddress("1600 Amphitheatre Parkway, california ");
System.out.println(addr);
will output the following address object (altitude = -1.0 means the altitude is unknown):
geo.google.datamodel.GeoUsAddress@c7e8a7[ _addressLine1=1600 Amphitheatre Pkwy _addressLine2= _city=Mountain View _county=Santa Clara _state=CA _postalCode=94043 _country=US _coordinate=geo.google.datamodel.GeoCoordinate@1fc3c84[_longitude=-122.081783, _latitude=37.423111, _altitude=geo.google.datamodel.GeoAltitude@1779885[_altitude=-1.0,_mode=CLAMP_TO_GROUND]] _accuracy=ADDRESS_LEVEL ]
Of course, you can change the request interval limit:
GeoAddressStandardizer st = new GeoAddressStandardizer("AABBCC", 1L*1000); //set request interval to 1 sec
GeoAddress addr = st.standardizeToGeoAddress("1600 Amphitheatre Parkway, Mountain View, CA");
st.setRateLimitInterval(2L*1000); //set to 2 sec
You can override the default configurations on how the http request is executed. For more information about the HttpClientParams object, see http://commons.apache.org/httpclient/preference-api.html#HTTP_connection_parameters
//For example, to change the http request time out value:
GeoAddressStandardizer st = new GeoAddressStandardizer("AABBCC");
HttpClientParams params = new HttpClientParams();
params.setSoTimeout((int)DateUtils.MILLIS_PER_MINUTE);
st.setHttpClientParams(params);
If the geocoding service is not able to geocode the input address, the address standardizer will throw a GeoException. This exception will have a status code that indicates the type of error. See http://www.google.com/apis/maps/documentation/reference.html#GGeoStatusCode for a list of these status code. (GeoException is now a checked exception since release 1.1, see changes-report.html )
try{
GeoAddressStandardizer st = new GeoAddressStandardizer("AABBCC");
st.standardizeToGeoAddress("a bad address");
}catch (GeoException e) {
System.out.println(e.getStatus());
System.out.println(e.getMessage());
}
For more details about the standardizer class, I encourage to take a look at the Javadoc . Also check out the FAQ section for more insights about this API.
See Examples . Source codes are available at sourceforge.net .