Development Guide

Local Navigation

Retrieve a GPS location by using a web page

Code sample: Retrieving a GPS location by using a web page

The following code sample demonstrates how to determine if a web page was loaded by the BlackBerry Browser and if the BlackBerry device supports GPS functionality. If these conditions are true, the web page receives the updated location information to start location tracking.

<!DOCTYPE html PUBLIC
    "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>GPS Testing</title>
    </head>
    <body>
        <script type="text/javascript">
var modeCellsite   = 0;
var modeAssisted   = 1;
var modeAutonomous = 2;

function locationChanged()
{
    alert("Lat " + blackberry.location.latitude +
        " Lon " + blackberry.location.longitude +
        " Time " + blackberry.location.timestamp );
    return true;
}

if ( window.blackberry && blackberry.location.GPSSupported )
{
    var isUpdated = false;
    var theCount = 0;

    alert("Location tracking is supported");

    blackberry.location.onLocationUpdate("locationChanged()");
    blackberry.location.setAidMode(modeAutonomous);

    while ( theCount++ < 10 && !isUpdated )
        isUpdated = blackberry.location.refreshLocation();
}
else
{
    document.write("Location tracking is not supported");
}
        </script>
    </body>
</html>

Retrieving a GPS location by using a web page

You can use JavaScript to configure the GPS mode, and determine the current location of the BlackBerry device by using the BlackBerry Browser.

You can use the following JavaScript properties and methods to access the Location API from the BlackBerry Browser.

JavaScript property

Description

blackberry.location.GPSSupported

This property returns true when GPS is supported by the BlackBerry device.

blackberry.location.latitude

This property returns the current latitude, in degrees, of the BlackBerry device. Positive values indicate northern latitude, negative values indicate southern latitude.

blackberry.location.longitude

This property returns the current longitude, in degrees, of the BlackBerry device. Positive values indicate eastern longitude, negative values indicate western longitude

blackberry.location.timestamp

This property returns time (in milliseconds since epoch) at which the blackberry.location object was updated.

JavaScript method

Description

blackberry.location.setAidMode(mode)

This method specifies which GPS mode the BlackBerry device will use to determine the GPS location. The mode can be any one of the following values:

  • 0 for Cell Site mode
  • 1 for Assisted mode
  • 2 for Autonomous mode

blackberry.location.refreshLocation()

This method requests an update of the location of the BlackBerry device. This method is asynchronous, so the script continues regardless of whether updated location information has been received. To ensure that location information is updated before reading it, you should first register a listener using blackberry.location.onLocationUpdate() that reads blackberry.location.latitude and blackberry.location.longitude, and then call refreshLocation() afterwards.

blackberry.location.onLocationUpdate("callback")

This method registers a listener that evaluates a string or calls a function whenever the BlackBerry device receives updated location information.

On BlackBerry devices running versions of BlackBerry Device Software earlier than version 4.6, this function must be passed as a string that is evaluated each time the location is refreshed. On BlackBerry devices running BlackBerry Device Software version 4.6 or later, you can pass a string, or use the method to register a callback function.

Once onlocationUpdate() has been invoked, the callback occurs whenever there is an update to the location information.

This can be as frequent as once every several seconds. If you have passed the method a function, you can cancel the callback using blackberry.location.removeLocationUpdate(). If you have passed a string, the callback cannot be removed.

blackberry.location.removeLocationUpdate()

This method removes a previously registered callback function. This method is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.

Back To Top

Was this information helpful? Send us your comments.