Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - GPS AND MAPS - DEVELOPMENT... User manual

GPS and BlackBerry Maps
Version: 4.7.0
Development Guide

SWD-596846-1209055709-001

Contents
1 GPS location information........................................................................................................................................................... 3
Specifying the source of GPS location information.................................................................................................................... 3
Get location information from cell site towers................................................................................................................... 3
Get location information from GPS satellites using PDE.................................................................................................. 4
Get location information from GPS satellites and the GPS receiver on a BlackBerry device....................................... 4
Get location information from the GPS receiver on a BlackBerry device........................................................................ 5
Getting GPS location information................................................................................................................................................. 6
Specify a response time for getting the location of the BlackBerry device..................................................................... 6
Get the location information for a BlackBerry device........................................................................................................ 6
Get the speed of the BlackBerry device, in meters per second........................................................................................ 6
Get the course of the BlackBerry device, in degrees.......................................................................................................... 7
Get the number of GPS satellites that a BlackBerry device tracks.................................................................................. 7
Get the time that a BlackBerry device application retrieved GPS information.............................................................. 7
Maintain a connection with GPS satellites......................................................................................................................... 7
Get continuous GPS readings using the cell site mode..................................................................................................... 7
Get GPS information during a call....................................................................................................................................... 7
Get location information updates........................................................................................................................................ 8
Change the criteria for obtaining location information..................................................................................................... 8
2BlackBerry Maps location information..................................................................................................................................... 9
Displaying location information on a BlackBerry device............................................................................................................ 9
Displaying location information in BlackBerry Maps......................................................................................................... 9
Open BlackBerry Maps to display the default map view................................................................................................... 12
Open BlackBerry Maps to display a location on a map..................................................................................................... 13
Open BlackBerry Maps to display multiple locations on a map....................................................................................... 14
Open BlackBerry Maps to display a route between locations on a map......................................................................... 15
Open BlackBerry Maps to display a custom map view...................................................................................................... 17
Open BlackBerry Maps to display the location for an address in the contact list.......................................................... 17
Start a BlackBerry device application from BlackBerry Maps........................................................................................... 19
Displaying location information in your application................................................................................................................... 23
Work with a map that displays in a UI field......................................................................................................................... 23
Converting latitudinal and longitudinal coordinates to pixel values............................................................................... 24
Requesting location information for an address......................................................................................................................... 25
Retrieve location information for an address stored in address fields............................................................................. 25

Retrieve location information for an address stored in a String....................................................................................... 26
Cancel a request for location information for an address................................................................................................. 26
Determine why a request for location information was unsuccessful............................................................................. 26
Open BlackBerry Maps from the browser.................................................................................................................................... 26
Clearing data from the map........................................................................................................................................................... 27
Clear data from a location document with an id attribute................................................................................................ 27
Clear data from all location documents with an id attribute............................................................................................ 27
Clear data from specific location documents with an id attribute................................................................................... 28
Clear all location data from a map....................................................................................................................................... 28
3 Glossary......................................................................................................................................................................................... 29
4 Provide feedback......................................................................................................................................................................... 30
5 Legal notice.................................................................................................................................................................................. 31

GPS location information 1
You can create a BlackBerry® device application to display the current latitudinal and longitudinal position of a BlackBerry device.
Depending on the mode for getting location information that you specify, the BlackBerry device application can also display
information such as the speed and route information. To create a BlackBerry device application to get location information, you
can use the Location API for Java® ME in the javax.microedition.location package (JSR 179).
The time it takes to retrieve the location of the BlackBerry device for the first time depends on several factors, such as the mode
for getting location information and the GPS signal strength. In autonomous mode, typical times are less than 2 minutes. In
assisted mode, typical times are less than 30 seconds.
To retrieve and display GPS location information, the BlackBerry device must support GPS technology and a valid SIM card must
be inserted in the BlackBerry device.
Specifying the source of GPS location information
GPS location information might be unavailable if the BlackBerry® device cannot receive signals from GPS satellites. This situation
can occur when something is obstructing the signals, such as buildings or dense clouds.
To specify the source of GPS location information, you specify the mode by creating an instance of the
javax.microedition.location.Criteria class, invoke the appropriate set methods, and then pass the instance
to LocationProvider.getInstance().
• cell site: Use this mode to get location information from cell site towers. This mode allows a BlackBerry device application
to retrieve location information faster than the assisted and autonomous modes. However, the accuracy of the location
information is low-level and does not provide tracking information such as speed or route information. Using this mode
requires wireless network coverage and that both the BlackBerry device and the wireless service provider support this mode.
• assisted: Use this mode to get location information from satellites using a PDE. This mode allows a BlackBerry device
application to retrieve location information faster than the autonomous mode and more accurately than the cell site mode.
To use this mode requires wireless network coverage, and the BlackBerry device and the wireless service provider must
support this mode.
•autonomous: Use this mode to get location information from the GPS receiver on the BlackBerry device without assistance
from the wireless network. This mode allows a BlackBerry device application to retrieve location information that has high-
accuracy, and does not require assistance from the wireless network. However, the speed at which this mode retrieves
location information is slower than the other modes.
Get location information from cell site towers
1. Create an instance of a Criteria object.
Criteria criteria = new Criteria();
Development Guide GPS location information
3

2. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT) to specify longitudinal accuracy is not
required.
3. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT) to specify latitudinal accuracy is not
required.
4. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost.
5. Invoke setPreferredPowerConsumption(POWER_USAGE_LOW) to specify power consumption is low.
6. Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.
LocationProvider provider = LocationProvider.getInstance(criteria);
Get location information from GPS satellites using PDE
1. Create an instance of a Criteria object.
Criteria criteria = new Criteria();
2. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT) to specify longitudinal accuracy is not
required.
3. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT) to specify latitudinal accuracy is not
required.
4. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost.
5. Invoke criteria.setPreferredPowerConsumption(int level) using one of
POWER_USAGE_MEDIUM, or NO_REQUIREMENT as the parameter to specify power consumption is medium or not
required.
6. Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.
LocationProvider provider = LocationProvider.getInstance(criteria);
Get location information from GPS satellites and the GPS receiver on a BlackBerry device
1. Create an instance of a Criteria object.
Criteria criteria = new Criteria();
2. Complete one of the following tasks:
Task Steps
Specify a level of
accuracy for
longitudinal and
latitudinal data.
a. Invoke criteria.setHorizontalAccuracy(int accuracy) using an
integer value that represents the accuracy, in meters.
b. Invoke criteria.setVerticalAccuracy(int accuracy) using an
integer value that represents the accuracy, in meters.
Development Guide Specifying the source of GPS location information
4

Task Steps
Specify that no level
of accuracy for
longitudinal and
latitudinal data is
required,
a. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT).
b. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT).
3. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost.
4. Invoke criteria.setPreferredPowerConsumption(POWER_USAGE_HIGH) to specify power
consumption is high.
5. Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.
LocationProvider provider = LocationProvider.getInstance(criteria);
Get location information from the GPS receiver on a BlackBerry device
1. Create an instance of a Criteria object.
Criteria criteria = new Criteria();
2. Complete one of the following tasks to get location information using the GPS receiver on a BlackBerry device :
Task Steps
Specify a level of accuracy,
with no cost and no power
consumption.
a. Invokecriteria.setHorizontalAccuracy(int accuracy) using
an integer value that represents the accuracy, in meters.
b. Invoke criteria.setVerticalAccuracy(int accuracy) using an
integer value that represents the accuracy, in meters.
c. Invoke criteria.setCostAllowed(false).
Specify a level of accuracy,
with cost and variable
power consumption.
a. Invokecriteria.setHorizontalAccuracy(int accuracy) using
an integer value that represents the accuracy, in meters.
b. Invoke criteria.setVerticalAccuracy(int accuracy) using an
integer value that represents the accuracy, in meters.
c. Invoke criteria.setCostAllowed(true).
d. Invoke
criteria.setPreferredPowerConsumption(int level) using
one of POWER_USAGE_LOW, POWER_USAGE_MEDIUM,or
NO_REQUIREMENT as the parameter.
Development Guide Specifying the source of GPS location information
5

Task Steps
Specify a level of accuracy,
with no cost and variable
power consumption.
a. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT).
b. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT).
c. Invoke criteria.setCostAllowed(false).
d. Invoke
criteria.setPreferredPowerConsumption(int level) using
one of POWER_USAGE_MEDIUM, POWER_USAGE_HIGH, or
NO_REQUIREMENT as the parameter.
3. Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.
LocationProvider provider = LocationProvider.getInstance(criteria);
Getting GPS location information
Specify a response time for getting the location of the BlackBerry device
Invoke Criteria.setPreferredResponseTime(), and specify the response time, in milliseconds.
Get the location information for a BlackBerry device
In a non-event thread, invoke LocationProvider.getLocation(int), providing a timeout, in seconds.
try {
// Specify -1 to have the implementation use its default timeout value
// for this provider.
Location location = provider.getLocation(-1);
} catch (Exception e) {
// handle LocationException, InterruptedException, SecurityException
// and IllegalArgumentException
}
Get the speed of the BlackBerry device, in meters per second
Invoke location.getSpeed().
Location location = provider.getLocation(-1);
float speed = mylocation.getSpeed();
Development Guide Getting GPS location information
6

Get the course of the BlackBerry device, in degrees
Invoke location.getCourse().
Location location = provider.getLocation(-1);
float course = mylocation.getCourse();
Get the number of GPS satellites that a BlackBerry device tracks
1. Invoke the Location.getExtraInfo() method using the NMEA MIME type as a parameter. The method returns
an encoded String that contains information on the number of GPS satellites.
Location location = provider.getLocation(-1);
String encodedStr = mylocation.getExtraInfo("application/X-jsr179-
location-nmea");
2. To retrieve the GPS satellite information, parse through the information in the returned String value.
Get the time that a BlackBerry device application retrieved GPS information
Invoke Location.getTimeStamp(). The time is retrieved from the GPS receiver on the BlackBerry® device.
Location location = provider.getLocation(-1);
myLocation.getTimeStamp();
Maintain a connection with GPS satellites
You can configure a BlackBerry® device application to query the Location API for GPS location information in an interval less
than 10 seconds.
Define a LocationListener with an interval value that is less than 10 seconds.
LocationProvider provider = LocationProvider.getInstance(criteria);
provider.setLocationListener(loclistener, 9, -1, -1);
Get continuous GPS readings using the cell site mode
Invoke the LocationProvider.getLocation() method within code that simulates the retrieval of GPS
information at fixed intervals.
Get GPS information during a call
Use the autonomous mode to retrieve GPS information.
Development Guide Getting GPS location information
7

Get location information updates
You can associate only one LocationListener object with a particular provider for GPS location information. The
BlackBerry® device application typically listens for updates on a separate thread.
1. Implement the LocationListener interface.
2. To register your implementation, invoke LocationProvider.setLocationListener().
Change the criteria for obtaining location information
1. Create a new Criteria object.
Criteria criteria2 = new Criteria();
2. Invoke the setHorizontalAccuracy(), setVerticalAccuracy(), setCostAllowed(), and
setPreferredPowerConsumption() methods of the new Criteria object to specify the new criteria.
3. Invoke LocationProvider.reset().
LocationProvider.reset();
4. Specify the LocationListener to null.
provider.setLocationListener(null, -1, -1, -1);
5. Invoke LocationProvider.getInstance() using the new Criteria object as a parameter to create a new
instance of a LocationProvider.
provider = LocationProvider.getInstance(criteria2);
6. Specify the LocationListener.
provider.setLocationListener(LocationListener listener, int interval, int
timeout, int maxAge);
Development Guide Getting GPS location information
8