Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Location-based services API

You can use the packages in the LBS API to:

  • Find a location
  • Display information in a map
  • Estimate the time and distance of a trip
  • Perform geofencing (mark an area to monitor so that you fire events when someone enters the area)

Finding a location

You can retrieve location information for a BlackBerry smartphone by using one of the following services:

  • GPS: Provides location information using GPS satellites. You can retrieve GPS location information 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.

  • Geolocation: Provides location information using cell tower positioning and WLAN access points. You do not require GPS technology on the smartphone to use the geolocation service. Geolocation is useful for applications that require an approximate location and that can be used indoors (for example, applications that recommend local points of interest). You can retrieve geolocation using the net.rim.device.api.gps package.

  • Geocoding and reverse geocoding: Provides geospatial coordinates for a street address (geocoding), and provides a street address for geospatial coordinates (reverse geocoding).

Displaying information in a map

After you retrieve the location for a BlackBerry smartphone, you can display the location information in BlackBerry Maps or custom maps.

BlackBerry Maps is a map and location application that can display a map, the location of the BlackBerry smartphone, a route from a starting location to a specific ending location, and points of interest on a map.

To create custom maps, you can add a MapField or RichMapField object to a screen, just as you add other UI components. Once you have a custom map, you can use it in any of the following ways:

  • Specify locations on the map
  • Control the behavior of the map
  • Create custom shapes and objects, and display them
  • Display mappable objects that can be updated dynamically as information changes
  • Add fields and overlays to the map
  • Customize the look and feel of the map
Your application can interact with BlackBerry Maps in the following ways:
  • Invoke BlackBerry Maps from your application using the Invoke.invokeApplication() method with MapsArguments parameters. You can display the following:

    • a location for an address in the Contacts application
    • a location for a landmark
    • a location at specific coordinates
    • a location or route by using a location document
    • a locations by using local search information
    • a KML overlay
  • Open BlackBerry Maps from the BlackBerry Browser.

You can create a location picker dialog box that allows a user to choose a location from a list of available selections that you define. You can define the location picker dialog box with the Location Picker API, which is provided in the net.rim.device.api.lbs.picker package. The location is passed using a javax.microedition.location.Landmark object.

Estimating the time and distance of a trip

You can retrieve the estimated time and distance it takes to travel between two points on a given date and at a given time using the Travel Time API. Currently, the Travel Time API provides estimates only for automobile travel in the United States and Canada.

To request a travel time estimate, retrieve an instance of the TravelTimeEstimator class. Use the requestArrivalEstimate() method and specify the coordinates for the starting and ending locations, and the starting time. The request is forwarded to a Travel Time server, which identifies a route between the starting and ending locations and uses live and historical traffic information to calculate a travel time estimate. The estimate reflects the known conditions on the specified date and at the specified time. The travel time estimate is returned by the TravelTimeEstimator using an instance of the TravelTime class.

Performing geofencing

You can use the Geofence class that is provided in the net.rim.device.api.location package to define geofenced areas and receive notifications when a BlackBerry smartphone user enters or leaves the specified area. A geofence is a virtual geographic area of interest that you can define by a radius around a location, or by coordinates that define a polygon for the location.

Your application must instantiate a Geofence object and implement the GeofenceListener to receive notifications for geofencing events (when a user enters or exits geofenced areas). Each instance of Geofence can process up to 20 monitored areas concurrently.