The concept of retrieving location information using GPS device and Location API is already discussed in one of the earlier post (http://www.xoriant.com/blog/mobile-application-development/location-based-programming.html ). In this article we are going to learn to use of Blackberry’s Location API and work with geocoding and reverse geocoding. Though, Geocoding and reverse Geocoding information could be used in multiple applications, a majority of applications will need to integrate the location information and display that on a Map.
To start with, let me introduce some terms:
Geocoding: is the process of finding associated geographic coordinates (often expressed as latitude and longitude) from other geographic data, such as street addresses, or zip codes (postal codes). With geographic coordinates, the features can be mapped and entered into Geographic Information Systems, or the coordinates can be embedded into media such as digital photographs via geotagging.
Reverse Geocoding: is the process of back (reverse) coding of a point location (latitude, longitude) to a readable address or place name. This permits the identification of nearby street addresses, places, and/or real subdivisions such as neighborhoods, county, state, or country. Combined with geocoding and routing services, reverse geocoding is a critical component of mobile location-based services to convert a coordinate obtained by GPS to a readable street address which is easier to understand by the end user.
Before we see the code part, let us look at the BlackBerry API (Locator) that facilitates the application to gain access to geospatial coordinates for an address and vice-versa i.e. retrieve a street address for given coordinates in case of reverse geocoding.
Locator is a Geocoding service in BlackBerry that allows you to obtain location address for an address. This service has static method “geocode”, “reverseGeocode” and as it should be obvious by now, geocode require address and returns coordinates, reverseGeocode require coordinates and returns the address information.
There are few things to keep in mind while Locator is used in the application
- LBS Map API is a pre-requisite for Locator API to work. Application may throw exception if the LS MAP API is not installed.
- Call to geocode is synchronous in nature. And at any given time there should be one call made using the Locator class. Application may throw exception if more than one call is made.
- Call to geocode and reverseGeocode should be made outside the event dispatch thread. Requests to these methods that are made on the event dispatch thread are denied and result in an exception.
Let us look how to use the Locator API to retrieve geospatial coordinates for an address using geocode.
- Packages required
import net.rim.device.api.lbs.*; import javax.microedition.location.*;
- Create a class and constructor
public class myGeocode
{
public myGeocode()
{
}
}
- Create a private Thread variable
private Thread geocoder;
- In constructor, create instance of the Thread class. As mentioned earlier, geocode cannot be performed on the application’s primary thread.
geocoder = new Thread(thread); geocoder.setPriority(Thread.MIN_PRIORITY); geocoder.start();
- In the class, create a Thread that invokdes a public run() method.
Runnable thread = new Runnable() {
public void run() {
AddressInfo addrInfo = new AddressInfo();
addrInfo.setField(AddressInfo.STREET, "Whitewood Dr");
addrInfo.setField(AddressInfo.CITY, "San Jose");
addrInfo.setField(AddressInfo.STATE, "California");
addrInfo.setField(AddressInfo.POSTAL_CODE, "95110");
addrInfo.setField(AddressInfo.COUNTRY, "US");
Coordinates startCoords = new Coordinates(37.386087,-121.889244, Float.NaN);
try {
Landmark[] results = Locator.geocode(addrInfo, startCoords);
}
catch ( LocatorException lex ) {
//thrown when The BlackBerry device is not sufficiently connected to send or receive over any transport.
}
catch (MapServiceException mex) {
// if the LBS Map API is not installed on a BlackBerry device or if an application makes more than one request at a time.
}
catch (IllegalThreadStateException itex) {
// if a request is made on the event dispatch thread
}
catch(IllegalStateException isex) {
// if there is no valid radio/wi-fi connection to send the request to
}
}
};
- The new two classes used above AddressInfo and Landmark, they allow application to pass formatted address object. However, overloaded geocode also accept “String” (e.g. Whitewood Dr, San Jose, Santa Clara, California 95110). This should also work and return the array of Landmark, the first array element contains the most relevant Landmark to the locator request. May be null if geocode request is cancelled or the request fails.
- startCoords are for hint to the geocode for starting the search specified in the request. This could also be null.
- Using the same class structure, let us see how to get the address info using coordinates.
Runnable thread = new Runnable() {
public void run() {
AddressInfo addrInfo = null;
int latitude = (int)(45.423488 * 100000);
int longitude = (int)(-80.32480 * 100000);
try {
Landmark[] results = Locator.reverseGeocode
(latitude, longitude, Locator.ADDRESS );
if ( results != null && results.length > 0 )
addrInfo = results[0].getAddressInfo();
} catch ( LocatorException lex ) {
//do something
}
}
};
- Pass one of the following parameters to Locator.reverseGeocode():
- Locator.ADDRESS: requests the nearest address or nearest street to the specified latitude/longitude
- Locator.CITY: returns a value that is focused on the city level Development Guide Retrieve an address by using reverse geocoding 44
- Locator.COUNTRY: returns a value that is focused on the country level
- Locator.PROVINCE_STATE: returns a value that is focused on the province or state level
Now, we’ve seen how to use the Locator API to get geospatial and address information. When we talk about coordinates, the next thing that comes to mind is how the same code can be extended to show the location on a map.
Well, BlackBerry also has a Map API that allows us to extend the above example and use the information as is i.e. to plot the address point on a map.
- Package required
import net.rim.blackberry.api.invoke.*; import net.rim.blackberry.api.maps.*;
- Maps is an inbuilt application in BlackBerry. This eliminates the user from writing core Map logic like displaying images, , calling Google Maps API and rendering the image in the application. All we have to do is invoke the external application (external to your application).
- Create class and constructor
public class showMap {
public showMap ()
{
}
}
- In constructor create an instance of MapView
MapView mapView = new MapView(); mapView.setLatitude(4328915); mapView.setLongitude(-8032480); mapView.setZoom(10);
- In the constructor, create an instance of the MapsArguments class using the MapView object as an argument. Invoke Invoke.invokeApplication() to open BlackBerry Maps and pass in the MapsArguments object.
MapsArguments mapsArgs = new MapsArguments(mapView); Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, mapsArgs);
Or you can also use the Lankmark object return by Locator.geocode
MapsArguments mapsArgs = new MapsArguments(results); Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, mapsArgs)
Location Based applications that incorporate maps are everywhere. The BlackBerry platform allows you to incorporate both location information and merge that into maps as we have seen in the blog post. It is important to note that the BlackBerry platform provide additional ways of showing a map using different inputs. You can also embed the map within the application. What I have covered here are the basics and hope that this article highlights the important nuances that could be useful for developers to try things quickly and then extend the same by building more complex applications.
Twitter
Facebook
LinkedIn
Flickr
SlideShare