Accessing location data using BPS

If you are developing your app in C, you can access geolocation data (latitude, longitude, altitude, heading, and speed) on the BlackBerry 10 device by using the Geolocation (geolocation.h) functions in the BlackBerry Platform Services library.

You must include the following header files from the BlackBerry Platform Services (BPS) library:

Not applicable

Not applicable

#include <bps/bps.h>
#include <bps/geolocation.h>

You must also set the Location permission in the bar.descriptor.xml file of your app.

The geolocation of a device refers to its position, heading, and speed in the world. Latitude, longitude, and heading are reported in degrees, while altitude is reported in meters above Mean Sea Level, and speed is reported in meters per second. Accuracy applies to the latitude, longitude, and altitude values and is reported in meters. You can also determine the number of GPS satellites that are used to report the device's geolocation.

The geolocation_set_period() function sets the period, in seconds, at which geolocation events are reported to the app. If the period is set to 0, a single geolocation event is delivered.

After your app registers to receive geolocation events using geolocation_request_events(), you can call bps_get_event() to retrieve the next available event from the BlackBerry Platform Services. After an event is received, you should determine whether it's a geolocation event by using bps_event_get_domain() and geolocation_get_domain(). You can also use navigator_get_domain() to determine whether the event was a request to close the app. To determine whether the event contains information about the current geolocation of the device, use bps_event_get_code() to compare the event code with the GEOLOCATION_INFO enumerator.

In the geolocation library, data is considered valid if the device has a GPS fix. A GPS fix is determined using the last update from the geolocation device driver. If the device does not have a GPS fix, the data is marked as invalid. The following geolocation attributes have associated functions that you can use to check for validity:

  • Altitude
  • Altitude accuracy
  • Heading
  • Speed
  • Number of GPS satellites used
  • Total number of GPS satellites reported

If the device cannot obtain a GPS fix but has Wi-Fi connectivity, the latitude, longitude, and accuracy are valid.

When the app no longer requires geolocation data, call geolocation_stop_events() to stop the delivery of geolocation events.

Code sample

Not applicable

Not applicable

/* 0 indiates that all events are requested */ 


while (!exit_application) {
  bps_event_t *event = NULL;
  /* -1 indicates that the function waites for an event before returning */
  bps_get_event(&event, -1);    

  if (event) {
    if (bps_event_get_domain(event) == geolocation_get_domain()) {
      if (event == NULL || bps_event_get_code(event) !=

      double latitude = geolocation_event_get_latitude(event);
      double longitude = geolocation_event_get_longitude(event);
      double accuracy = geolocation_event_get_accuracy(event);

      double altitude = geolocation_event_get_altitude(event);
      bool altitude_valid =

      double altitude_accuracy =
      bool altitude_accuracy_valid = 

      double heading = geolocation_event_get_heading(event);
      bool heading_valid =

      double speed = geolocation_event_get_speed(event);
      bool speed_valid = geolocation_event_is_speed_valid(event);

      double num_satellites =
      bool num_satellites_valid =
/* 0 indicates that all events are stopped */

Related resources

Sample apps


Last modified: 2015-05-07

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus