Table of Contents for

HTML5 Geolocation

The W3C Geolocation API is a specification that provides scripted access to geographical location information associated with the hosting device.^[8] It is meant to be a “high-level interface” so that the developer using it does not need to worry about details such as how the location information is being gathered. It does not matter whether the device is using GPS, IP Address, or Cell ID; only the geolocation information itself is important. The one caveat that the specification makes, however, is that there is no guarantee that the location returned from the API is the actual location of the device. This should come as no surprise, given that GPS may not have enough visible satellites to determine an accurate position, there may not be enough cell towers to get a proper triangulation from a Cell ID, or an IP Address could be spoofed to give a completely false location. Because of these, and other possible reasons, the developer may feel reasonably confident in the results returned by the API, but should never rely on any information blindly.

<script type="text/javascript" 
    src="http://code.google.com/apis/gears/gears_init.js"></script>

<script type="text/javascript" 
    src="http://code.google.com/apis/gears/gears_init.js"></script> 
<script type="text/javascript" src="geo.js"></script>
<script type="text/javascript">
  function initialize() {
    if (geo_position_js.init())
      geo_position_js.getCurrentPosition(show_position, error_handler, 
        { enableHighAccuracy: true }
      );
    else
      alert('Geolocation functionality is not available.');
</script>

In this chapter, and the book in general, the focus is on a JavaScript implementation of the W3C Geolocation API to work within HTML5 applications. The interface’s implementation is being included in all modern browsers for both desktop and mobile devices. Because it is a newer API, however, there has been a need for other APIs to step in and create the cross-browser implementations needed to include older devices and browsers. The geo-location-javascript API, described in geo-location-javascript, is one such API.

The downside to using these APIs is they do not share all the functionality that the W3C Geolocation API has, leaving gaps in what can be developed. As you will see in the rest of this chapter, the W3C Geolocation API is a robust and thorough interface that allows for the development of web applications that rival applications created natively on devices.

The W3C Geolocation API specifies a general implementation for the objects, properties, and methods associated with the Geolocation interface. One object holds the whole implementation of the W3C Geolocation API—the Geolocation object. This object can be used within JavaScript to gather geolocation information about the device on which the browser resides. The Geolocation object is a new property of the global window.navigator Browser Object, and can be accessed from the window.navigator.geolocation instantiation.

As with all JavaScript objects, it is a best practice to first test for the existence of an object’s implementation within a browser before using it, as the following code illustrates:

if (window.navigator.geolocation) {
  // do some geolocation stuff
} else {
  // the browser does not natively support geolocation
}

In the preceding code, the existence of an implementation of the geolocation property is tested, and if it exists, the code will do geolocation processing, otherwise something else will need to be tried.

The Geolocation object contains three public methods, as described in Table 3-2. All geolocation functionality stems from these methods and the callback functions they take as parameters.

Once it has been verified that the browser supports the W3C Geolocation API, requests can be made to get the current position of the device in question. This is done using the getCurrentPosition() method. The getCurrentPosition() method requires at least one parameter, a position callback function. Optionally, it can also take an error callback function, and an options parameter. It is called like this:

navigator.geolocation.getCurrentPosition(successCallback, errorCallback, 
    options);

The first parameter, successCallback, will be called when a successful position has been discovered by the inner workings of the API. The second parameter, errorCallback, is optional and will be called when there is an error in gathering a position. The final parameter, options, is a PositionOptions object that is also optional.

The following code snippet shows the getCurrentPosition() more fully:

if (window.navigator.geolocation) {
  navigator.geolocation.getCurrentPosition(successCallback, errorCallback, 
      options);
} else {
  alert('Your browser does not natively support geolocation.');
}

function successCallback(position) {
  // Do something with a location here
}

function errorCallback(error) {
  // There was a problem getting the location
}

var options = {
  enableHighAccuracy: true,
  maximumAge: 60000,
  timeout: 45000
};

navigator.geolocation.getCurrentPosition(successCallback, errorCallback, 
    options);

var options = {
  maximumAge: 600000
};

navigator.geolocation.getCurrentPosition(successCallback, errorCallback, 
    options);

var options = {
  maximumAge: Infinity
};

navigator.geolocation.getCurrentPosition(successCallback, errorCallback, 
    options);

There are times when an application requires an updated position every time the device changes location. In these cases, a call to the watchPosition() method is warranted in place of calling the getCurrentPosition() method. The watchPosition() method has the same basic structure as the getCurrentPosition() method. It also takes a successCallback parameter that is required, as well as two optional parameters: errorCallback and options.

The major difference between the two methods is that the watchPosition() method will return a value immediately upon being called which uniquely identifies that watch operation. The watch operation itself is an asynchronous operation. It is called like this:

var watcher = navigator.geolocation.watchPosition(successCallback, 
                errorCallback, options);

The first parameter, successCallback, will be called when a successful position has been gathered by the API. The second parameter, errorCallback, is optional and will be called when there is an error in gathering a position. The final parameter, options, is a PositionOptions object that is also optional. The variable, watcher, is the unique identifier for this particular watch operation.

The following code snippet shows how to use watchPosition():

var watcher = null;
var options = {
  enableHighAccuracy: true,
  timeout: 45000
};

if (window.navigator.geolocation) {
  watcher = navigator.geolocation.watchPosition(successCallback, 
              errorCallback, options);
} else {
  alert('Your browser does not natively support geolocation.');
}

function successCallback(position) {
  // Do something with a location here
}

function errorCallback(error) {
  // There was a problem getting the location
}

navigator.geolocation.clearWatch(watcher);

var watcher = null;
var options = {
  enableHighAccuracy: true,
  timeout: 45000
};

if (window.navigator.geolocation) {
  watcher = navigator.geolocation.watchPosition(successCallback, 
              errorCallback, options);
} else {
  alert('Your browser does not natively support geolocation.');
}

function successCallback(position) {
  navigator.geolocation.clearWatch(watcher);
  // Do something with a location here
}

Once a location request has been gathered by the API, the successCallback function is called. This works the same using either the getCurrentPosition() or updatePosition() methods. The successCallback function is passed one parameter from the API, a Position object.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>A First Geolocation Example</title>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no"/>
    <meta charset="utf-8"/>'
    <script type="text/javascript">
      var options = {
        enableHighAccuracy: true,
        maximumAge: 1000,
        timeout: 45000
      };

      if (window.navigator.geolocation) {
        navigator.geolocation.getCurrentPosition(successCallback, 
            errorCallback, options);
      } else {
        alert('Your browser does not natively support geolocation.');
      }

      function successCallback(position) {
        var output = '';

        output += "Your position has been located.\n\n";
        output += 'Latitude: ' + position.coords.latitude + "°\n";
        output += 'Longitude: ' + position.coords.longitude + "°\n";
        output += 'Accuracy: ' + position.coords.accuracy + " meters\n";
        if (position.coords.altitude)
          output += 'Altitude: ' + position.coords.altitude + " meters\n";
        if (position.coords.altitudeAccuracy)
          output += 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + 
              " meters\n";
        if (position.coords.heading)
          output += 'Heading: ' + position.coords.Heading + "°\n";
        if (position.coords.speed)
          output += 'Speed: ' + position.coords.Speed + " m/s\n";
        output += 'Time of Position: ' + position.timestamp;

        alert(output);'
      }

      function errorCallback(error) {
        // There was a problem getting the location
      }
    </script>
  </head>
  <body>
    <div>A First Geolocation Example</div>
  </body>
</html>

function dd2dms(degree, lat_long) {
  this.deg = Math.abs(parseInt(degree));
  this.min = (Math.abs(degree) - this.deg) * 60;
  this.sec = this.min;
  this.min = Math.abs(parseInt(this.min));
  this.sec = Math.round((this.sec - this.min) * 60 * 1000000) / 1000000;
  this.sign = (degree < 0) ? -1 : 1;
  this.dir = (lat_long == 'lat') ? ((this.sign > 0) ? 'N' : 'S') : 
      ((this.sign > 0) ? 'E' : 'W');
  this.toString = function(dir) {
    if (isNaN(dir))
      return (this.deg * this.sign) + "\u00b0 " + this.min + "' " + 
	      this.sec + '" ';
    else
      return this.deg + "\u00b0 " + this.min + "' " + this.sec + '" ' + 
	      this.dir;
  };
}

function dms2dd(deg, min, sec, dir) {
  if (dir) {
    this.sign = (dir.toLowerCase() == 'w' || dir.toLowerCase() == 's') ? -1 :
        1;
    this.dir = (dir.toLowerCase() == 'w' || dir.toLowerCase() == 's' || 
	    dir.toLowerCase() == 'n' || dir.toLowerCase() == 'e') ? 
		dir.toUpperCase() : '';
  } else {
    this.sign = (deg < 0) ? -1 : 1;
    this.dir = '';
  }
  this.dec = Math.round((Math.abs(deg) + ((min * 60) + sec) / 3600) * 
      1000000) / 1000000;
  this.toString = function(dir) {
    if (isNaN(dir) || this.dir == '')
      return (this.dec * this.sign) + "\u00b0";
    else
      return this.dec + "\u00b0" + ' ' + this.dir;
  }  
}

alert(new dd2dms(40.567534, 'long').toString(1)); // output: 40° 34' 3.1224" E
alert(new dms2dd(40, 34, 3.1224, 'E').toString(1)); // output: 40.567534° E

There are several reasons why a location request could fail within the API, and with any of these the errorCallback function is called when it is provided with either the getCurrentPosition() or updatePosition() methods. When provided, the errorCallback function is passed one parameter from the API, a PositionError object.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>A First Geolocation Example</title>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no"/>
    <meta charset="utf-8"/>
    <script type="text/javascript">
      var options = {
        enableHighAccuracy: true,
        maximumAge: 1000,
        timeout: 45000
      };

      if (window.navigator.geolocation) {
        navigator.geolocation.getCurrentPosition(successCallback, 
            errorCallback, options);
      } else {
        alert('Your browser does not natively support geolocation.');
      }

      function successCallback(position) {
        var output = '';

        output += "Your position has been located.\n\n";
        output += 'Latitude: ' + position.coords.latitude + "°\n";
        output += 'Longitude: ' + position.coords.longitude + "°\n";
        output += 'Accuracy: ' + position.coords.accuracy + " meters\n";
        if (position.coords.altitude)
          output += 'Altitude: ' + position.coords.altitude + " meters\n";
        if (position.coords.altitudeAccuracy)
          output += 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + 
              " meters\n";
        if (position.coords.heading)
          output += 'Heading: ' + position.coords.Heading + "°\n";
        if (position.coords.speed)
          output += 'Speed: ' + position.coords.Speed + " m/s\n";
        output += 'Time of Position: ' + position.timestamp;

        alert(output);
      }

      function errorCallback(error) {
        switch (error.code) {
          case error.PERMISSION_DENIED:
            alert('You have denied access to your position.');
            break;
          case error.POSITION_UNAVAILABLE:
            alert('There was a problem getting your position.');
            break;
          case error.TIMEOUT:
            alert('The application has timed out attempting to get your ' +
			    location.');
              break;
        }
      }
    </script>
  </head>
  <body>
    <div>A First Geolocation Example</div>
  </body>
</html>

Privacy is an important matter, not only with the W3C Geolocation API, but with all geolocation applications available today. Companies know how dearly individuals hold their privacy, and take many precautions to safeguard any data collected from the user. If a user is ever in any doubt as to a company’s policies and procedures, he should check with the company’s Privacy Policy regarding user data.

To address security and privacy considerations with the W3C Geolocation API, the specification outlines that no locations may be sent to web applications without the express permission of the user. The standard way this is being implemented across browsers is to provide an information bar that, as per the W3C specification, lists the URI of the document requesting a location (see Figure 3-1). The user can opt to always allow access for the site with a checkbox indicating this site-level access, which can be undone at any time within the settings of the browser itself.

Figure 3-1. Opt-in policy in Chrome

Unless the user has granted the application a site-level access retained within the specific browser, the permissions given by the user will expire at the end of the current browsing session. With such opt-in policies, any implementation of the W3C Geolocation API should achieve adequate privacy functionality and alleviate a user’s anxiety towards their location data. The best a developer can do is guarantee proper handling of a user’s data, while users would be wise to follow a policy of only granting access to their personal data to trusted individuals and sites.