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.


Was this information helpful? Send us your comments.