Location-Based Services

This category contains the packages that you can use to access the location, map, and landmark data on a BlackBerry® device.

For more information about LBS, visit www.blackberry.com/go/devguides to read the BlackBerry Java Application Location-Based Services Development Guide. For additional resources, visit www.blackberry.com/developers.

Retrieve the location of a BlackBerry device by using GPS [back to top]

Packages: javax.microedition.location, net.rim.device.api.gps

You can create a BlackBerry® device application to retrieve the geographic location of a BlackBerry device. The values for the location information are returned as the latitude, longitude, and altitude.

You can interact with the GPS receiver on a BlackBerry device by using one the following GPS modes:

The GPS mode that you use to retrieve the location information can affect the initial speed of a location fix, the level of location accuracy, and the amount of resources that are consumed on the BlackBerry device.

You can retrieve location information by using the JSR 179 Location API in the javax.microedition.location package or the BlackBerry extensions to JSR 179 in the net.rim.device.api.gps package that are provided in BlackBerry® Java Development Environment 5.0. The BlackBerry extensions to JSR 179 is supported on BlackBerry devices that run BlackBerry Device Software 5.0.0 or later. The JSR 179 Location API is supported on BlackBerry devices that run BlackBerry® Device Software 4.0.2 or later. For more information about GPS support on BlackBerry devices, visit http://www.blackberry.com/knowledgecenterpublic to read DB-00615.

You can retrieve the location of a BlackBerry device by performing the following steps.

Step 1: Specify the GPS mode.

Click here for a code sample: Specifying the GPS mode

/* JSR 179 */
Criteria myCriteria = new Criteria();

/* JSR 179 extension */
BlackBerryCriteria myBlackBerryCriteria = new BlackBerryCriteria(…);

Step 2: Retrieve a location provider.

Click here for a code sample: Retrieving a location provider

/* JSR 179 */
LocationProvider myProvider = LocationProvider.getInstance(myCriteria);

/* JSR 179 extension */
BlackBerryLocationProvider myBlackBerryProvider =
    (BlackBerryLocationProvider) LocationProvider.getInstance(myBlackBerryCriteria);

Step 3: Make a GPS request based on the frequency of the location fix.

Click here for a code sample: Making a GPS request based on the frequency of the location fix

/*
 * Single location fix
 */
 
/* JSR 179 */
Location myLoc = myProvider.getLocation(…);

/* JSR 179 extension */
BlackBerryLocation myBlackBerryLoc = myBlackBerryProvider.getLocation(…);

/*
 * Continuous location fixes
 */

 /* JSR 179 */
myProvider.setLocationListener(…);

/* JSR 179 extension */
myBlackBerryProvider.setLocationListener(…);

Step 4: Retrieve the location of a BlackBerry device.

Click here for a code sample: Retrieving the location of a BlackBerry device

/* JSR 179 */
double lat = myLoc.getQualifiedCoordinates().getLatitude();
double lng = myLoc.getQualifiedCoordinates().getLongitude();
double alt = myLoc.getQualifiedCoordinates().getAltitude();

/* JSR 179 extension */
double lat = myBlackBerryLoc.getQualifiedCoordinates().getLatitude();
double lng = myBlackBerryLoc.getQualifiedCoordinates().getLongitude();
double alt = myBlackBerryLoc.getQualifiedCoordinates().getAltitude();

When you use the JSR 179 Location API to retrieve the location of a BlackBerry device, a single location request returns a Location that is provided by a LocationProvider. The GPS mode that the LocationProvider uses to retrieve the location is specified in a Criteria instance.

Similarly, when you use the BlackBerry extension to JSR 179 to retrieve the location of a BlackBerry device, a single location request returns a BlackBerryLocation that is provided by a BlackBerryLocationProvider. The GPS mode that the BlackBerryLocationProvider uses to retrieve the location is specified in a BlackBerryCriteria instance.

For more information about designing a GPS application for the BlackBerry device, visit http://www.blackberry.com/knowledgecenterpublic to read DB-00671.

Click here for a code sample: Determining satellite information


// The following code sample demonstrates how to request a location fix
// and then determine the current number of satellites in view, tracked
// satellites, average satellite signal quality, GPS data source
// (internal GPS or external Bluetooth® GPS puck), and the GPS mode.			

import java.util.*;
import net.rim.device.api.gps.*;
import javax.microedition.location.*;

public class handleGPS
{
    static GPSThread gpsThread;
    static int satCount;
    static int signalQuality;
    static int dataSource;
    static int gpsMode;

    public handleGPS()
    {
        gpsThread = new GPSThread();
        gpsThread.start();
    }

    private static class GPSThread extends Thread
    {
        public void run()
        {
            try
            {
                BlackBerryCriteria myCriteria =
                  new BlackBerryCriteria(GPSInfo.GPS_MODE_AUTONOMOUS);

                try
                {
                    BlackBerryLocationProvider myProvider =
                      (BlackBerryLocationProvider)
                        LocationProvider.getInstance(myCriteria);

                    try
                    {
                        BlackBerryLocation myLocation =
                          (BlackBerryLocation)myProvider.getLocation(300);

                        satCount= myLocation.getSatelliteCount();
                        signalQuality =
                          myLocation.getAverageSatelliteSignalQuality();
                        dataSource = myLocation.getDataSource();
                        gpsMode = myLocation.getGPSMode();

                        SatelliteInfo si;
                        StringBuffer sb = new StringBuffer("[Id:SQ:E:A]\n");
                        String separator = ":";

                        for (Enumeration e = myLocation.getSatelliteInfo();
                          e!=null && e.hasMoreElements(); )
                        {
                            si = (SatelliteInfo)e.nextElement();
                            sb.append(si.getId() + separator);
                            sb.append(si.getSignalQuality() + separator);
                            sb.append(si.getElevation() + separator);
                            sb.append(si.getAzimuth());
                            sb.append('\n');
                        }
                    }
                    catch ( InterruptedException iex )
                    {
                        return;
                    }
                    catch ( LocationException lex )
                    {
                        return;
                    }
                }
                catch ( LocationException lex )
                {
                    return;
                }
            }
            catch ( UnsupportedOperationException uoex )
            {
                return;
            }

            return;
        }
    }
}

Advantages of using the BlackBerry extension to JSR 179

Item Advantage
BlackBerryLocationProvider

Keep the GPS receiver active by specifying an interval, in seconds, that is greater than 0 when you invoke BlackBerryLocationProvider.pauseLocationTracking(). For example, you can specify 60 so that the application tries to retrieve a location fix every 60 seconds. The location fix is not provided to your application during the paused state.

BlackBerryCriteria
  • Specify an intial GPS mode when you create a BlackBerryCriteria object.
  • Specify a GPS failover mode to use when the intial GPS mode is unsuccessful.
  • Specify a subsequent GPS mode to use after a successful first location fix is retrieved.
  • Specify an interval to wait before automatically restarting the GPS receiver when a location fix is not successfully retrieved. You can specify intervals to a maximum of 15 minutes and a minimum of 2 seconds, with a maximum of three automatic retries.
  • Specify whether the satellite tracking information is required. The satellite tracking information includes the number of satellites in view, the ID associated with the satellite, and the signal strength, elevation, and azimuth.
BlackBerryLocation
  • Retrieve information about an error that is associated with a BlackBerryLocation object by invoking BlackBerryLocation.getError(). For example, invoke BlackBerryLocation.getError() when a BlackBerryLocation.GPS_ERROR occurs.
  • Retrieve the details about the satellites that a BlackBerry device is tracking by invoking BlackBerryLocation.getSatelliteInfo(). Invoking this method returns an enumeration of SatelliteInfo objects.
GPSInfo

Query the GPS capabilities on the BlackBerry device so that you can verify if a GPS mode is supported, by invoking GPSInfo.isGPSModeAvailable().

Retrieve landmark and street address information by using geocoding services [back to top]

Packages: net.rim.device.api.lbs, javax.microedition.location

In BlackBerry® Java Development Environment 5.0, the net.rim.device.api.lbs.Locator API provides the geocoding methods that can allow you to request geospatial coordinates for a street address. It also provides the reverse geocoding methods that can allow you to request a street address for a geospatial coordinate.

You can use the geocode() method to request geospatial coordinates. A successful request returns an array of Landmark objects.

You can use the reverseGeocode() methods to request an approximate address, city, province/state or country information. A successful request returns an array of Landmark objects. A Landmark object can contain a display label name, a description, the geospatial coordinates, and a street address.

Requests for geocoding and reverse geocoding information are synchronous and can be interrupted. A BlackBerry device application can use the Locator class to make only one request at a time.

Your application must request geocoding or reverse geocoding information outside of the event dispatch thread. Requests made on the event dispatch thread are denied and result in a IllegalThreadStateException. Each request for geocoding or reverse geocoding information is sent to the LBS Locate Server. If a request is unsuccessful, a LocatorException is thrown with an error code that indicates the reason for the failure. If a request fails or stalls at the transport level, it is cancelled as specified by the value for REQUEST_TIMEOUT.

If the LBS Map API module (net_rim_bb_lbs_api) is not installed on a BlackBerry device, then requests for geocoding or reverse geocoding information throw a MapServiceException.

Request results are not cached on the BlackBerry device.

Click here for a code sample: Retrieving a street address by using reverse geocoding

import net.rim.device.api.lbs.*;
import javax.microedition.location.*;

public class myReverseGeocode
{
    private Thread reverseGeocode;

    public myReverseGeocode()
    {
        reverseGeocode = new Thread(thread);
        reverseGeocode.setPriority(Thread.MIN_PRIORITY);
        reverseGeocode.start();
    }

    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 )
            {
            }
        }
    };
}

Interact with BlackBerry Maps [back to top]

Packages: net.rim.blackberry.api.invoke, net.rim.blackberry.api.maps, net.rim.blackberry.api.menuitem, net.rim.device.api.lbs

Invoke BlackBerry Maps

You can create a BlackBerry® device application that interacts with BlackBerry® Maps. BlackBerry Maps is a map and location application that can display a map, the location of the BlackBerry device, a route from a starting location to a specific ending location, and points of interest on a map.

Your application can interact with BlackBerry Maps in the following ways:

BlackBerry Maps can be installed on BlackBerry devices that run BlackBerry® Device Software 4.2 or later.

You can use the MapsArguments class in the net.rim.blackberry.api.invoke package to create a BlackBerry device application that interacts with BlackBerry Maps.

Click here for a code sample: Invoking BlackBerry Maps by using the default settings

import net.rim.blackberry.api.invoke.*;

public class invokeMaps
{
    public invokeMaps()
    {
        Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments());
    }
}

Displaying a map in a UI field

You can display a map in a UI field by using use the net.rim.device.api.lbs.MapField class. Your BlackBerry® device application can use a MapField object to get data either from a map server for location-based services or a BlackBerry device with BlackBerry® Maps installed. If location information is not present on the BlackBerry device, the BlackBerry device application can use a MapField object to request data from the map server.

The MapField class allows a BlackBerry device application to change and retrieve the properties of the map including the zoom level, the center of the map, and the current rotation of the map. To use the MapField class, BlackBerry Maps must be installed on the BlackBerry device and the BlackBerry device must be able to download data from the map server for location-based services.

For more information, see Application Integration. To download a sample application that demonstrates how to use the MapField class, visit www.blackberry.com/go/mapfieldsample.

Add a menu item to BlackBerry Maps

You can add a menu item to the menu of BlackBerry® Maps by using the ApplicationMenuItem class and registering the ApplicationMenuItem with the ApplicationMenuItemRepository (type MENUITEM_MAPS). When you register the menu item, you must use an ApplicationDescriptor. When your ApplicationMenuItem is invoked, your application is passed a MapView context object.

For more information, see Application Integration or visit www.blackberry.com/knowledgecenterpublic to read article DB-00618.


Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.