HTML5 New Feature Series: Geolocation

Today handheld devices are so popularly spreading over our around, and the position feature plays an vital role in the applications developed for these devices. Some applications, such as Uber, can find the nearest car for you by your current position, and the group-buying application can recommend the nearby theaters and food for you via your position information, also, map application can make an optimal road map for you by your current position and help you get to the destination, we can say that, position information is definitely essential for mobile application.

And to follow this trend, HTML5 provides us the Geolocation library, with this feature we are able to build an application in which we can easily implement the functionalities that we mentioned above. Then today I will show you the whole landscape of this feature.

First of all, we can obtain a

Geolocation

instance via

geolocation

property of

navigator

:



And there are three common-used methods below showing:

getCurrentPosition: to get current position

watchPosition: to trace position changes

clearWatch: cancel the watch operation above

We will take a look at the

getCurrentPosition

method in the first place, the following is its signature:

navigator.geolocation.getCurrentPosition(success[, error[, options]]);

The first parameter is a success handler, and the second is error handler, the third one is an optional configure for function’s running. Now we attempt to call this function:

navigator.geolocation.getCurrentPosition(function(position) {
//success handler code goes here
console.log(position);
}, function(error) {
//error handler code goes here
console.log(error);
}, {//options
enableHighAccuracy: true,
timeout: 5000,
maximumAge: 0
});

Once the code is running, there will be a confirm dialog coming out to request the permission for locating:



If we click

Allow

button, that means we permit the program to locate, and success handler will be triggered after the position information is returned, we printed the

position

in the console:



We can see that

position

is actually a

Geoposition

instance which contains

coords

and

timestamp

two properties, and the latter is a timestamp when position data is obtained, also, there are several position relevant properties included in

coords

:

accuracy: the accuracy measured in meters

altitude: the altitude measured in meters, if no height sensor provides data for browser, this value will be

null

altitudeAccuracy: the altitude accuracy measured in meters, likewise, this property will be set to

null

if no height data provided

speed: the speed of device’s moving, measured in

m/s

, if no data can get from device, this value will be

null

heading: the current moving direction, measured in degrees, [0 ,360), indicates how far off from true north by clockwise, 0 represents true north, 90 is true east, and 180 indicates true south, 270 means true west. Note that if

speed

is

0

,

heading

will be

NaN

, and if device is not able to provide direction data, this property value will be

null

longitude: longitude expressed in decimal

latitude: latitude expressed in decimal

We will receive these data in success handler, and do next processing according to actual device and application scenario.

Go back to previous confirm dialog, if we click the

Block

, it will fail to request permission, accordingly, the error handler will be invoked, and an

error

object will be passed in this handler, the following is the error object we printed in console:



We can see that

error

is an instance of

PositionError

, it contains

code

and

message

properties, representing error type and error message separately, thereinto, three error types are included:

1: PERMISSION_DENIED - failed to request permission due to user’s rejection

2: POSITION_UNAVAILABLE - failed to get position caused by an internal error

3: TIMEOUT - didn’t get position data after running out the time we configured

That’s the error handler above, commonly if an error occurred when getting position, we need to capture it and handle with it properly to get better experience, it’s very important.

In the invocation of

getCurrentPosition

, we also provide the third parameter, just a simple object which contains a few of configurations, they are specified to config the runtime arguments for this function:

enableHighAccuracy: by default, it’s a

false

value, and if specified as

true

, that means it’s required to get the data as accurate as it can under the condition of supported by device, but it will lead to certain consumption in battery and time.

timeout: the timeout measured in milliseconds, indicates to stop the operation after running out the time, the default is

Infinity

maximumAge: to specify a longest time to cache the position data, during this period, it will obtain the data from cache when attempting to get position, it’s measured in milliseconds.

Above is all about

getCurrentPosition

, in some cases such as map navigation, we need the latest position to plan a new road map for user, and apparently getting data once is not able to meet our requirement, therefore, we need the

watchPosition

method:

watchId = navigator.geolocation.watchPosition(success[, error[, options]]);

watchPosition

method is similar with

getCurrentPosition

, the only difference is that

success

will be running repeatedly, once got the latest data,

success

will be triggered again, similarly, the

error

will also execute repeatedly if it failed to get up-to-date position serially.

We may notice that a

watchId

is returned in the signature, it indicates the current ID of watch operation, and we can clear this operation by calling the

clearWatch

function with this

watchId

after tracing position is done:

navigator.geolocation.clearWatch(watchId);

That’s the introduction of the common-used three APIs regarding

Geolocation

, we can choose appropriate method according to the actual situation to get user’s position.

Although

Geolocation

has been supported by the majority of browsers, in order to take care of the browser in low version, we still need to detect if it supports:

if ('geolocation' in navigator) {
// getting usr's position
} else {
// tips: your position is not available
}

At last we will illustrate how it works in real development with a simple program:

var API = {
//get recommended data by current longitude and latitude
getSurroundingRecommendations: function(longitude, latitude, callback) {
//simulate data obtaining from server.
setTimeout(function() {
var data = [
{
//item
},
{
//item
}
];
callback(data);
}, 500);
}
};

document.addEventListener('DOMContentLoaded', function() {
//detect if Geolocation is supported
if (!'geolocation' in navigator) {
console.log('Geolocation is not supported in your browser');
return;
}

var successHandler = function(position) {
var coords = position.coords,
longitude = coords.longitude,
latitude = coords.latitude;

API.getSurroundingRecommendations(longitude, latitude, function(data) {
console.log(data);
});
},
errorHandler = function(error) {
console.log(error.code, error.message);
},
options = {
enableHighAccuracy: true,
timeout: 5000,
maximumAge: 0
};

navigator.geolocation.getCurrentPosition(successHandler, errorHandler, options);

}, false);

In the code, we firstly define a method to get the recommended data by user’s position, and then after the DOM is loaded, we start to get current position data and call this method to obtain mock data, note that, we will do further operations with the data in real development.

That’s all about it, thanks.