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
- 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.
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.