Jenkov.com
Tutorials Books About
Html5

1 HTML5 Tutorial
2 HTML5 DOCTYPE
3 HTML5 Language
4 HTML5 Character Encoding
5 HTML5 Form Fields
6 HTML5 Local Storage
7 HTML5 Geo Location
8 HTML5 Messaging
9 HTML5 Drag and Drop
10 HTML5 Web Workers
11 HTML5 Semantic Elements
12 HTML5 header Element
13 HTML5 hgroup Element
14 HTML5 Footer
15 HTML5 nav Element
16 HTML5 article element
17 HTML5 time Element




HTML5 Geo Location


The HTML geo location feature enables your web application to obtain the geographical position of your website visitors. Geo location is not actually part of the HTML5 specification, but since HTML5 has become the de facto label for all the new features in HTML and JavaScript, I have included geo location in this HTML5 tutorial.

Security and Privacy

The user has to accept that your website accesses their location via a browser dialog, so you cannot use it for spying on your visitors without their knowing.

Accessing Geo Location

Geo location is accessed via JavaScript, through the navigator.geolocation object in the browser. The geo location object allows you to access geo location through two primary functions:

  1. getCurrentPosition()
  2. watchPosition()

The getCurrentPosition() function returns the location of the visitor as a one-time snapshot. The watchPosition() function returns the location of the visitor every time the location changes. It does so by calling the given success or error callback functions whenever the position changes.

Both functions take the following parameters:

  • Success callback function
  • Error callback function (optional)
  • Geo location options object (optional)

As you can see, some of the parameters are optional. Here is an example that accesses the users geo location, and passes only the success callback function to getCurrentPosition():

navigator.geolocation.getCurrentPosition(
    function(position) {
        alert("your position is: "
                + position.coords.latitude + ", "
                + position.coords.longitude);
    }
);

To try the example, click this button:

The geo location is obtained asynchronously. That means, that when you call getCurrentPosition() or watchPosition() the functions return immediately. When the browser knows the location of the user, and the user has accepted that the website may access the geo location, the success callback function is called. If an error occurs, the error callback function is called instead.

The Position Object

The position object passed to the success callback function looks like this:

double latitude         // read only attribute
double longitude        // read only attribute
double accuracy         // read only attribute

double altitude         // read only attribute
double altitudeAccuracy // read only attribute
double heading          // read only attribute
double speed            // read only attribute

The latitude and longitude properties contains the geopgrahical coordinates of the position. The accuracy property contains the accuracy of the location in meters. The lower the accuracy is, the more precise the location is.

The altitude, altitudeAccuracy, heading and speed are available only if the device running the browser has a GPS embedded. Otherwise these properties are set to null.

The altitude property contains the altitude of the user. The altitudeAccuracy contains the accuracy in meters of the altitude. The heading property tells the direction the user is moving. The value is in degrees (0-360) relative to true north. The speed property contains the users speed in meters per second, if available.

Speed

The speed property seems only to have a value if you are using the watchPosition() method. The browser apparently needs a few positions in order to calculate a speed.

The Error Callback Function

If obtaining the users geo location fails, the error callback function passed to either getCurrentPosition() or watchPosition() will be called. Failing to obtain the geo location may fail for the following reasons:

  • The user denies the website access to geo location.
  • The device running the browser cannot obtain the geo location, e.g. if the device is in a tunnel, underground etc. where GPS satelite signals cannot be received.
  • The device is too long time about obtaining the position, and the call times out.

The error callback function receives an object with two properties, like this:

short     code    // unsigned read only attribute.
DOMString message // read only attribute.

The value of the code attribute will be one of:

  • 1, meaning PERMISSION_DENIED
  • 2, meaning POSSITION_UNAVAILABLE
  • 3, meaning TIMEOUT

The message attribute contains a textual description of the error. This error may be useful for a developer, but may not make much sense for the website user.

The Geo Location Options Object

The getCurrentPosition() and watchPosition() functions can take a geo location options object as the third parameter. This options object can contain the following properties:

    enableHighAccuracy     // true or false
    timeout                // milliseconds
    maximumAge             // milliseconds

The enableHighAccuracy property can be either true or false. A value of true signals to the browser that if the device running the browser has a GPS, it should be enabled. Keep in mind that the GPS takes a lot of power, so don't require it enabled unless it is necessary with the high accuracy.

The timeout property tells the browser how long time to wait when trying to obtain a position, before timing out and calling the error callback function instead of the success callback function.

The maximumAge attribute tells the browser the maximum age in milliseconds of a cached location, that your application will accept. A value of 0 means that the browser must obtain a new location upon each call to the success callback function.

A Full HTML5 Geo Location Example

Here is a code example that uses both a success callback handler, an error callback handler, and an options object:

navigator.geolocation.getCurrentPosition(
    function(position) {
        alert("your position is: "
                + position.coords.latitude + ", "
                + position.coords.longitude);
    }
    ,
    function(errorObject) {
        alert("Error obtaining position");
    }
    ,
    {
      enableHighAccuracy : true,
      timeout    : 3000,
      maximumAge : 60000
    }
);



Connect with me: Newsletter - Get all my free tips!