How to Incorporate Location into Your BlackBerry Applications

If you have ever been in an unfamiliar place or stuck in traffic and looking for an alternate route, then you already know the magic that is GPS. One of the hottest areas in smartphone development today is location-based services, and BlackBerry is on the cutting edge when it comes to providing those services. In this article we will discuss BlackBerry’s support of JSR 179, and learn to incorporate GPS functionality into our applications.

Before we delve in any further into this article, I am going to assume that you are already familiar with programming basic BlackBerry applications, and that you have the required development environments and simulators installed on your computer. If not, I suggest taking a peek at BlackBerry’s Developer Zone to get up to speed.

GPS Information and the BlackBerry

Not all BlackBerry devices support GPS (Global Positioning System) technology, but on the ones that do, applications exist that allow the user to display their current position on a map in real time. In addition, applications can supply directions, both textual and image-driven, and suggest alternate routes. They can even give the user satellite and street level imagery. To achieve these wonders, BlackBerry applications rely on the Location API for Java Platform (JSR 179). We will be working with this JSR throughout the remainder of this article.

For starters, we will look at methods and modes used to obtain local GPS information. There are three Location modes available to use. The first is cell site, which lets us retrieve information from cell site towers and the strength of the user’s signal. Of all the location modes, this method is the fastest, but be forewarned – that speed comes with a disadvantage: the accuracy is sub-par and you cannot obtain speed or routing information. Note that cell site support depends on the carrier.

To get location information using the cell site mode, create a new Criteria object, like so:

Criteria criteria = new Criteria():

Next you will need to Invoke the following:

criteria.setHorizontalAccuracy(NO_REQUIREMENT); //this tells the program that there is no requirement for longitude accuracy

criteria.setVerticalAccuracy(NO_REQUIREMENT); //the same as above, but with regards to latitude

criteria.setCostAllowed(true); //specifies that the cell site mode can result in a fee

setPreferredPowerConsumption(POWER_USAGE_LOW); //set the power consumption to low

After this you will need to invoke LocationProvider.getInstance(), which in turn stores the information in a LocationProvider object. To do so, type in the following:

LocationProvider provider = LocationProvider.getInstance(criteria);

{mospagebreak title=Getting Information via PDE}

The second location mode we can use to retrieve data is the assisted mode. This mode obtains information via satellites with a Position Determination Entity, or PDE. The up side to this method is that it is more accurate than the cell site mode, and faster than the third method (autonomous). The down side is that it is not as accurate as the autonomous method, except in a few rare situations.

To get the location using the assisted mode, create a new Criteria object, in the following manner:

Criteria criteria = new Criteria():

Next you will want to Invoke the following:

criteria.setHorizontalAccuracy(100); //indicates that there is a requirement for horizontal accuracy

criteria.setVerticalAccuracy(NO_REQUIREMENT); //indicates that there is no accuracy required for latitude

criteria.setCostAllowed(true); //indicates that the cell site mode can result in a fee

criteria.setPreferredPowerConsumption(POWER_USAGE_MEDIUM) //tells the program that there is a medium power usage requirement

The last thing to do is to Invoke LocationProvider.getInstance(), which stores the information in a LocationProvider object:

LocationProvider provider = LocationProvider.getInstance(criteria);

Getting Information with GPS

The last location mode is known as autonomous, as referenced above. This information is retrieved from a GPS receiver on the BlackBerry device and does not rely on a wireless network. It provides the best accuracy for location, but unfortunately is slower than the other methods in terms of time-to-first-fix.

If we wish to get accurate information, we do as before — create an instance of a Criteria object, using the same method as before:

Criteria criteria = new Criteria():

Then we will Invoke the following, this time changing our requirement:

criteria.setHorizontalAccuracy(50); //indicates that there is a requirement for longitudinal accuracy (this value is optional)

criteria.setVerticalAccuracy(50); //indicates that there is a requirement for latitudinal accuracy (this value is optional)

Note that both of these values require a value in meters.

If we wish to get an approximate value, we do so like this:

criteria.setHorizontalAccuracy(NO_REQUIREMENT); // that there is no accuracy required for longitude

criteria.setVerticalAccuracy(NO_REQUIREMENT); // that there is no accuracy required for latitude

Next we will deny fees:


And finally, we need to create a LocationProvider object based on these criteria:

LocationProvider provider = LocationProvider.getInstance(criteria);

There are a few other methods for retrieving and storing location information; we will touch upon those in a later article. For now though, let’s move on and learn to actually display the data.

{mospagebreak title=Display Our Data}

Retrieving information is great, but its true power comes in displaying it. After all, what good is data if you can’t share it? Fortunately for us, displaying data is fairly simple. The first step is learning XML. Learning XML is necessary because BlackBerry Maps uses location documents to display information on a map. The location document itself is no more than a string that contains some XML elements and their related attributes. Because of this, you will need to know at least a little XML, and understanding the hierarchy of elements will make displaying your data a breeze.

There are three main elements in a location document. They are the <lbs>, <getRoute> and <location> elements. The <lbs> element is used to contain every documentation element in a location document. For this reason, all location documents begin with <lbs> and end with the closed </lbs> element.

Meanwhile, the <getRoute> element holds the route information. If you wish to display any route information on your map, you will need to place two <location> elements between your opening and closing <getRoute> tags. The first of these <location> tags acts as the starting point; the second acts as the ending point.

Location elements hold the information for a location and can contain many attributes. Note however, that if you are placing a <location> element in a <getRoute> element, you can only use the x and y attributes.

The following is a list of attributes that you can associate with the <location> tag:

y – This integer data type holds the latitude in decimal degrees, multiplied by 100,000.

x – Another integer data type that holds the longitude in decimal degrees, multiplied by 100,000.

address – This string data type store the address.

city – This string data type stores the city.

country – Another string data type. This stores the country.

categories – This string data type stores the category.

description – A string data type that allows you to describe a location.

email – A string data type that stores email addresses.

fax – A string that hold fax numbers.

label – A string data type which acts as a label for a point on the map.

phone – A string that stores phone numbers.

postalCode – A string that stores postal codes.

rating – A double data type that allows for rating information, ranging from 0-5.

url – A string that hold URL information.

zoom – An integer that lets you set the zoom level from 0 to MAX_ZOOM.

{mospagebreak title=Creating the Location Document}

Now that we know the XML elements and attributes that make up a location document, we can create one. There are two types of location document that we can create. The first is one that uses only required elements:


<location y= ‘latitude’ x =’longitude’ label =’MyLabel’ description=’This is my description’ />

<location y= ‘latitude’ x =’longitude’ label =’MyLabel’ description=’This is my description’ />

<location y= ‘latitude’ x =’longitude’ label =’MyLabel’ description=’This is my description’ />


The second type of location document is one that uses both required and optional elements:


<location y= ‘latitude’ x =’longitude’ label =’MyLabel’ description=’This is my description’ zoom=’MAX_ZOOM’ address=’address’ rating=’3′ />


Displaying the Data

The last step in the process is to actually display the data on a map. To do so, create a new string and feed it the location information for your location:

String document = “<location-document><location x=’ -3942102′ y=’1234567′ label =’New Mexico, USA’ description=’New Mexico’ zoom=’5′ />


Next, you will need to Invoke the following:

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments(MapsArguments.ARG_LOCATION_DOCUMENT, Document));

It’s that simple.

While it is beyond the scope of this article, it should also be noted that geoencoding and route generation are both supported.

One other important thing to note is a feature that makes the BlackBerry stand out from the crowd – namely, ephemeris information. In Standalone mode, the user’s device must scan the entire sky to find satellites. With ephemeris information, BlackBerry devices are updated every 3-4 days with the approximate location of the satellites, resulting in a much faster first fix in Standalone mode.


We have literally only touched the tip of the iceberg when it comes to incorporating location into your BlackBerry apps, but I think this is a good starting point. We’ll continue looking at how to display location, and other location retrieval techniques, in an upcoming article, so be sure to drop by often.

Google+ Comments

Google+ Comments