Help Center

Local Navigation

Object: blackberry.location

Availability

BlackBerry® Device Software version 4.1 or later

The blackberry.location object is a property of the blackberry object. It provides access to the GPS location of the BlackBerry device. The GPS location refers to the geographical co-ordinates, latitude and longitude, of the BlackBerry device.

blackberry.location properties

Property name

Type

Description

Status

Availability

GPSSupported

boolean

When true, this property indicates that GPS positioning is supported by the BlackBerry® device.

read only

4.1 or later

latitude

double

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

To ensure that the most accurate co-ordinate is returned, you should register a listener using blackberry.location.onLocationUpdate() and acquire the location information within the callback.

read only

4.1 or later

longitude

double

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

To ensure that the most accurate co-ordinate is returned, you should register a listener using blackberry.location.onLocationUpdate() and read acquire the location information within the callback.

read only

4.1 or later

timestamp

unsigned long

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

This property is only supported on BlackBerry devices running BlackBerry® Device Software version 4.6 or later.

read only

4.6 or later

blackberry.location methods

Method name

Description

Availability

onLocationUpdate()

Registers a callback method that is called when the location is updated using blackberry.location.refreshLocation().

4.1 or later

refreshLocation()

Requests an update of the location of the BlackBerry® device.

4.1 or later

removeLocationUpdate()

Removes a previously registered callback method.

4.6 or later

setAidMode()

Specifies which method the BlackBerry device will use to obtain the GPS location.

4.1 or later

Method: blackberry.location.onLocationUpdate()

Availability

BlackBerry® Device Software version 4.1 or later

The onLocationUpdate() 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 method 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.

Syntax

blackberry.location.onLocationUpdate( callbackFunction | callbackString )

Parameters

Parameter

Type

Description

callbackFunction

Function

A JavaScript® function.

For BlackBerry devices running versions of the BlackBerry Device Software that are earlier than version 4.6, you must specify the callback as a string.

callbackString

String

A string to be evaluated when the location information is updated.

Return values

None.

Exceptions

None.

Method: blackberry.location.refreshLocation()

Availability

BlackBerry® Device Software version 4.1 or later

The refreshLocation() 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.

Syntax

blackberry.location.refreshLocation()

Parameters

None.

Return values

Returns true if the GPS location of the BlackBerry device is successfully updated; otherwise, returns false.

Exceptions

None.

Method: blackberry.location.removeLocationUpdate()

Availability

BlackBerry® Device Software version 4.6 or later

The removeLocationUpdate() method removes a previously registered callback method.

This method is only supported on BlackBerry® devices running BlackBerry® Device Software version 4.6 or later.

Syntax

blackberry.location.removeLocationUpdate( callbackFunction )

Parameters

Parameter

Type

Description

callbackFunction

Function

A JavaScript® function previously registered by blackberry.location.onLocationUpdate().

Return values

None.

Exceptions

None.

Method: blackberry.location.setAidMode()

Availability

BlackBerry® Device Software version 4.1 or later

The setAidMode() method specifies which method the BlackBerry® device will use to obtain the GPS location.

The device can obtain location information in one of three ways.

Aid Mode

Value

Description

Cellsite

0

This method uses the GPS location of the active cellsite tower to provide first order GPS information. It provides the least accurate location information; however, it is the fastest location mode.

This location method requires network connectivity and carrier support.

Assisted

1

This method uses the network to provide ephemeris satellite data to the device chip. It provides the GPS location faster than the autonomous mode and more accurately than the cellsite mode.

This location method requires network connectivity and carrier support.

Autonomous

2

This method uses the GPS chip on the BlackBerry device without assistance from the network. The autonomous mode provides the first GPS location in the slowest amount of time.

Syntax

blackberry.location.setAidMode( aidMode )

Parameters

Parameter

Type

Description

aidMode

int

The method used to obtain the GPS location. The value for this parameter may be one of:

  • 0 — Cellsite

  • 1 — Assisted

  • 2 — Autonomous

Return values

None.

Previous topic: JSON Object: Address

Was this information helpful? Send us your comments.