Geocoding
As well as offering a few helpful methods for coordinating conversion and distance measuring, the CoordinateHelper class also has some methods that allow for geocoding, that is, conversion between street addresses and latitude/longitude pairs.
Before writing applications that employ geocoding, think carefully about how it will be used. Geocoding relies on servers provided by Apple (for iOS devices) and Google (for Android). If you are considered to be "over-using" the service, you may find your applications rate limited or banned. A few good rules of thumb are:
Make at most one geocoding request per user action.
If the user could make multiple geocoding requests against the same location, it is worth caching the results. Doing so will make the application more responsive.
If the user is moving around and the application is using geocoding to update the user's address, only send requests when the user has moved a significant distance
and a significant amount of time has passed. A request rate higher than 1 per minute is likely to be frowned upon.
Do not start a geocoding request unless the result is seen immediately by the user. Applications running in the background should continue gettting location updates without asking for new geocoding data until the application is brought to the foreground again.
Note:
Not all handsets support geocoding. It is important to check the result of canUseGeocodingApi() before calling other geocoding methods.
To convert from a latitude/longitude pair to a street address, use the findPlacesBy() method:
if(CoordinateHelper.canUseGeocodingApi())
{
Location myLocation = new Location();
myLocation.latitude = myLatitude; //double value, defined elsewhere
myLocation.longitude = myLongitude;
CoordinateHelper.findPlacesBy(myLocation, 10, new GeoCallback());
}
The GeoCallback object has an array of Placemark objects passed back in its onPlacesFound() method, along with the original myLocation object. Usually, the results are ordered from closest to furthest match.
To get a set of coordinates from a street address, use the findLocationsBy() method:
if(CoordinateHelper.canUseGeocodingApi())
{
String address = "10 Downing Street, London, England";
CoordinateHelper.findLocationsBy(address, 10, new GeoCallback());
}
The GeoCallback object has an array of Location objects passed to it, indicating potential matches.