API Tutorials
deCarta mapping tutorials for developers of location enabled mobile and web applications. These HTML5 tutorials are a first in a continuous series provided by deCarta.
HTML5 Geolocation API and deCarta Mobile JavaScript API
Overview
The Geolocation API lets you share your geographic location with trusted web sites. The latitude and longitude are available to JavaScript via simple API calls. Although it is completely hidden from the concerns of the developer, this new API gathers location information from a large variety of aggregated sources including IP address, Wi-Fi and Bluetooth MAC address, RFID, Wi-Fi connection location, or device GPS and GSM/CDMA cell IDs. The location is returned with a given accuracy depending on the best location information source available. This API has found wide adoption across most modern desktop browsers, but more interestingly, across most new smart phone and tablet browsers. For Location based applications, this API opens the door to new innovation.
This functionality already exists in the following desktop browsers:
| IE | Firefox | Safari | Chrome | Opera |
|---|---|---|---|---|
| 9.0+ | 3.5+ | 5.0+ | 5.0+ | 10.6+ |
This functionality already exists in the following mobile browsers:
| Opera Mobile | iPhone / iPad | Android | Blackberry | Bada Dolfin |
|---|---|---|---|---|
| 10.6+ | 3.0+ | 2.0+ | 6.0+ | 2.0+ |
Another important detail about the use of geo location, is that it is opt-in, which mean that when you code tries to access the location of the device, the browser will pop-up an info bar telling the user that the web page is attempting the access location, and prompting the user to either confirm or deny the action. You must put provisions in your code for those users who opt out of sharing location.
Getting started
The geolocation API is based on the common asynchronous callback based paradigm which is familiar to anyone who has done JavaScript programming. The reason calls for location are asynchronous is because the detection of location may take an indeterminate about of time and usually you do not want the call to block or freeze the application.
For attaining the current position of the user, use the following function:
void getCurrentPosition(in PositionCallback successCallback,
in optional PositionErrorCallback errorCallback,
in optional PositionOptions options);
The function signature takes three parameters. A success callback function which is passed the location information in the form of the position object. An error callback function which will be called if any errors or timeouts occur in retrieving the location. The third and final argument is an optional 'options' object that contains details about the location determination.
This is an example of using the geolocation API with the deCarta HTML5 mobile API, using Navteq data:
navigator.geolocation.getCurrentPosition(
// argument 1 'success callback'
function(position){
var pos = new deCarta.Mobile.Position(position.coords.latitude, position.coords.longitude);
deCarta.Sample.map.zoomTo(10);
deCarta.Sample.map.centerOn(pos);
},
// argument 2 'error callback'
function(error){
switch(error.code) {
case error.TIMEOUT:
alert("TIMEOUT");
break;
case error.PERMISSION_DENIED:
alert("PERMISSION DENIED")
break;
case error.POSITION_UNAVAILABLE:
alert("POSITION UNAVAILABLE")
break;
}
},
// argument 3 'optional options for location determination'
{
enableHighAccuracy:false,
timeout:30000,
maximumAge:1000*60*60
}
);
For the exact details on the object structure of each callback function, see:
success callback: http://dev.w3.org/geo/api/spec-source.html#position_interface
error callback: http://dev.w3.org/geo/api/spec-source.html#position_error_interface
options parameter: http://dev.w3.org/geo/api/spec-source.html#position_options_interface
Continuous Tracking
The second interesting API for geolocation is the watch position function. With watch position, your callback function will be alerted every time the position changes (the devices moves). This can be used to build web based tracking applications of all sorts. With NAVTEQ data, this could also provide some really interesting web based driving directions and guidance solutions through cross platform web technologies.
The watch position interface is the same as the get current position interface, except it returns an ID which can be used to stop the reporting:
long watchPosition(in PositionCallback successCallback,
in optional PositionErrorCallback errorCallback,
in optional PositionOptions options);
void clearWatch(in long watchId);
The code above could be changed to used watch position by simple changing the function name from
getCurrentPosition to watchPosition. We have also changed the options to:
enableHighAccuracy:true // to get real GPS for more accurate positioning
maximumAge:30000 // to get fresh positions
navigator.geolocation.watchPosition(
// argument 1 'success callback'
function(position){
var pos = new deCarta.Mobile.Position(position.coords.latitude, position.coords.longitude);
deCarta.Sample.map.zoomTo(10);
deCarta.Sample.map.centerOn(pos);
},
// argument 2 'error callback'
function(error){
switch(error.code) {
case error.TIMEOUT:
alert("TIMEOUT");
break;
case error.PERMISSION_DENIED:
alert("PERMISSION DENIED")
break;
case error.POSITION_UNAVAILABLE:
alert("POSITION UNAVAILABLE")
break;
}
},
// argument 3 'optional options for location determination'
{
enableHighAccuracy:true,
timeout:10000,
maximumAge:30000
}
);