The BlackBerry® Browser engine can retrieve geographic information about the users current location through use of the HTML5 Geolocation API. This article explains how developers can leverage this capability in their own Web content either targeting the native browser application or applications created using the BlackBerry® WebWorks™ Application Platform. The content described in this article is supported by BlackBerry® Device Software 5.0 and higher.
The following attachments can be found at the end of this article:
html5_geolocation_demo.zip - sample web content that demonstrates how to retrieve and use geographic information within an application. This content can either be loaded directly using the BlackBerry browser, or packaged into an application using the BlackBerry WebWorks Application Platform.
How To: Retrieving geographic Information
The getCurrentPosition() method accepts two required and one optional parameters:
- Required: name of function to be called once GPS info has been acquired.
- Required: name of function to be called if an error occurs.
- Optional: object (of type PositionOptions) that contains parameters about what type of GPS fix to acquire.
//First test to see that the browser supports the Geolocation API
if (navigator.geolocation !== null)
onSuccess, geolocationError, options);
alert("HTML5 geolocation is not supported.");
Next, define the call back methods that can be called by the getCurrentPosition() method of the geolocation API.
The error callback method has a single parameter (of type PositionError) that contains two attributes: code and message. Developers should be aware that various conditions may exist that affect a users ability to retrieve GPS information on their BlackBerry Smartphone (e.g. IT Policies, Carrier restrictions, user-defined Access permissions, etc). You should always have appropriate support in the error call-back method to support these types of scenarios.
alert("An unexpected error occurred [" + error.code + "]: " + error.message);
The success callback method has a single parameter (of type Position) that contains two attributes: time and coordinates. The coordinates object (of type Coordinates) contains seven attributes: latitude, longitude, altitude, accuracy, altitudeAccracy, heading and speed. Note: The heading and speed attributes are not supported by the BlackBerry Web Platform and developers can expect these fields to be
//Extract information about the users current position:
var time = position.timestamp;
var coordinates = position.coords;
//Retrieve geographic information about the GPS fix:
var lat = coordinates.latitude;
var lon = coordinates.longitude;
var alt = coordinates.altitude;
var acc = coordinates.accuracy;
var altAcc = coordinates.altitudeAccuracy;
var head = coordinates.heading;
var speed = coordinates.speed;
alert("You are located at " + lat + ", " + lon);
How To: Using Geolocation in application functionality
Once you've retrieve the geographic information about your user from the GPS, you can introduce contextually-aware functionality to your applications. This is one of the principles of Super App design.
As demonstrated in the attached samples, some examples of providing a highly contextualized experience to your users can include:
- Displaying content that is relevant to their current location, such as targeted advertising or information about local points of interest.
- Providing directions to a location point of interest (e.g. a restaurant, store or movie theatre) based on their current location
- Automatically retrieving and displaying weather forecast information about the users current location