geo.google
Class GeoAddressStandardizer

java.lang.Object
  geo.google.GeoAddressStandardizer

public class GeoAddressStandardizer
extends Object

Address Standardizer class. Note: The http connection is synchronized in this class! you need to create multiple standardizer if you need concurrency.
This class provides a set of methods for standardizing an address.

Note that this class standardizes the input address by sending a http request to google's geocoder service (http://www.google.com/apis/maps/documentation/). This service requires an ApiKey which you need to sign up for before you can use this class.

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) per IP address for several minutes, then Google will block you for a day. This class automatically enforces this limit by only sending out request in 5.769 second interval. You can change the value of this time interval via the constructor.

  long timeTilNextStart = _rateLimitInterval - ( System.currentTimeMillis() - _lastRequestTime);
  if(timeTilNextStart > 0){
      Thread.sleep(timeTilNextStart); //sleep for some time
  }
  _lastRequestTime = System.currentTimeMillis();
 

For more information about this service, see http://www.google.com/apis/maps/index.html

Author:

jliang

Constructor Summary

GeoAddressStandardizer(String apiKey)
Register a google geocoding API key at http://www.google.com/apis/maps/signup.html

GeoAddressStandardizer(String apiKey, long rateIntervalInMillis)
Register a google geocoding API key at http://www.google.com/apis/maps/signup.html

Method Summary

String	getApiKey()
org.apache.commons.httpclient.params.HttpClientParams	getHttpClientParams() Parameters for controlling the http connection.
long	getRateLimitInterval()
void	setApiKey(String apiKey)
static void	setConnectionManager(org.apache.commons.httpclient.HttpConnectionManager manager) Sets the HttpConnectionManager to be used for connecting to the geocoding service
static void	setHttpClient(org.apache.commons.httpclient.HttpClient client) Sets the HttpClient to be used for connecting to the geocoding service
void	setHttpClientParams(org.apache.commons.httpclient.params.HttpClientParams httpClientParams)
void	setRateLimitInterval(long rateLimitInterval)
<ReturnType> ReturnType	standardize(String addressLine, XmlMappingFunctor<ReturnType> mappingFunction) Standardize an address using google's geocoding service;
GeoAddress	standardizeToGeoAddress(GeoUsAddress usAddress) Deprecated. Use standardizeToGeoAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.
GeoAddress	standardizeToGeoAddress(String addressLine) Deprecated. Use standardizeToGeoAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.
List<GeoAddress>	standardizeToGeoAddresses(GeoUsAddress usAddress) Standardize an address using google's geocoding service;
List<GeoAddress>	standardizeToGeoAddresses(String addressLine) Standardize an address using google's geocoding service;
GeoCoordinate	standardizeToGeoCoordinate(String addressLine) Standardize an address using google's geocoding service;
GeoUsAddress	standardizeToGeoUsAddress(GeoUsAddress usAddress) Deprecated. Use #standardizeToUsGeoAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.
GeoUsAddress	standardizeToGeoUsAddress(String addressLine) Deprecated. Use standardizeToGeoUsAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.
List<GeoUsAddress>	standardizeToGeoUsAddresses(GeoUsAddress usAddress) Standardize an address using google's geocoding service;
List<GeoUsAddress>	standardizeToGeoUsAddresses(String addressLine) Standardize an address using google's geocoding service;

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GeoAddressStandardizer

public GeoAddressStandardizer(String apiKey)

Register a google geocoding API key at http://www.google.com/apis/maps/signup.html

GeoAddressStandardizer

public GeoAddressStandardizer(String apiKey,
                              long rateIntervalInMillis)

Register a google geocoding API key at http://www.google.com/apis/maps/signup.html

Method Detail

setConnectionManager

public static void setConnectionManager(org.apache.commons.httpclient.HttpConnectionManager manager)

Sets the HttpConnectionManager to be used for connecting to the geocoding service

setHttpClient

public static void setHttpClient(org.apache.commons.httpclient.HttpClient client)

Sets the HttpClient to be used for connecting to the geocoding service

Parameters:

client -

getHttpClientParams

public org.apache.commons.httpclient.params.HttpClientParams getHttpClientParams()

Parameters for controlling the http connection. http://jakarta.apache.org/commons/httpclient/preference-api.html#HTTP_parameters

Returns:

setHttpClientParams

public void setHttpClientParams(org.apache.commons.httpclient.params.HttpClientParams httpClientParams)

standardizeToGeoAddress

public GeoAddress standardizeToGeoAddress(GeoUsAddress usAddress)
                                   throws GeoException

Deprecated. Use standardizeToGeoAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.

Standardize an address using google's geocoding service;

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoUsAddress

public GeoUsAddress standardizeToGeoUsAddress(GeoUsAddress usAddress)
                                       throws GeoException

Deprecated. Use #standardizeToUsGeoAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.

Standardize an address using google's geocoding service;

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoAddress

public GeoAddress standardizeToGeoAddress(String addressLine)
                                   throws GeoException

Deprecated. Use standardizeToGeoAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.

Standardize an address using google's geocoding service;

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoUsAddress

public GeoUsAddress standardizeToGeoUsAddress(String addressLine)
                                       throws GeoException

Deprecated. Use standardizeToGeoUsAddresses(String) instead. This method only returns the first return geocoded address, which is not always the best standardization.

Standardize an address using google's geocoding service;
This method returns the FIRST returned geocoded address.

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoUsAddresses

public List<GeoUsAddress> standardizeToGeoUsAddresses(String addressLine)
                                               throws GeoException

Standardize an address using google's geocoding service;

Parameters:

addressLine -

Returns:

zero or more GeoAddress objects in a List.

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoAddresses

public List<GeoAddress> standardizeToGeoAddresses(String addressLine)
                                           throws GeoException

Standardize an address using google's geocoding service;

Parameters:

addressLine -

Returns:

zero or more GeoAddress objects in a List.

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoUsAddresses

public List<GeoUsAddress> standardizeToGeoUsAddresses(GeoUsAddress usAddress)
                                               throws GeoException

Standardize an address using google's geocoding service;

Parameters:

addressLine -

Returns:

zero or more GeoAddress objects in a List.

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoAddresses

public List<GeoAddress> standardizeToGeoAddresses(GeoUsAddress usAddress)
                                           throws GeoException

Standardize an address using google's geocoding service;

Parameters:

addressLine -

Returns:

zero or more GeoAddress objects in a List.

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardizeToGeoCoordinate

public GeoCoordinate standardizeToGeoCoordinate(String addressLine)
                                         throws GeoException

Standardize an address using google's geocoding service;

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

standardize

public <ReturnType> ReturnType standardize(String addressLine,
                                           XmlMappingFunctor<ReturnType> mappingFunction)
                       throws GeoException

Standardize an address using google's geocoding service;

Parameters:

mappingFunction - - a mapping function that converts the kml string returned by google's geocoding service to any other object type.

Throws:

GeoException - Indicates something unexpected occurs. It also includes a GeoStatusCode to signal problems about the status of the geocoding request.

getApiKey

public String getApiKey()

setApiKey

public void setApiKey(String apiKey)

getRateLimitInterval

public long getRateLimitInterval()

setRateLimitInterval

public void setRateLimitInterval(long rateLimitInterval)