Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

Using HTML5 Geolocation in your Web or BlackBerry WebWorks applications

by Retired on ‎11-05-2010 03:19 PM (25,461 Views)



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.


Through the use of the HTML5 to Gears™ JavaScript® toolkit, HTML5 geolocation can be supported on Device Software version 5.0.  Developers are encouraged to use this technique to update any of their Gears Geolocation code to HTML5 Geolocation and allow their content to easily be supported and managed across both BlackBerry Device Software 5.0 and BlackBerry® 6.



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 following snippet of JavaScript code shows how to use the Geolocation object to retrieve geographic information about the users current location.  As shown in this example, the geolocationSuccess callback method is invoked when a GPS fix has been acquired and the geolocationError method is invoked if an error occurs. 

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.


function getPosition()
//First test to see that the browser supports the Geolocation API
if (navigator.geolocation !== null)
var options;
navigator.geolocation.getCurrentPosition(geolocationSuccess, geolocationError, options);
else {
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.

function geolocationError(error)
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 null.


function geolocationSuccess(position)
//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:


  1. Displaying content that is relevant to their current location, such as targeted advertising or information about local points of interest.
  2. Providing directions to a location point of interest (e.g. a restaurant, store or movie theatre) based on their current location
  3. Automatically retrieving and displaying weather forecast information about the users current location




Users Online
Currently online: 7 members 1,084 guests
Please welcome our newest community members: