HTML 5 Geolocation: An Advanced Example

In our article

HTML 5 Geolocation: A Practical Example

we created a scenario for a Store Locator to illustrate all of the most commonly used HTML 5 Geolocation properties and methods. We are now going to step beyond the common to the uncommon and illustrate some of the less used but arguably more interesting properties and methods like

coords.altitude

,

coords.heading

and

watchPosition()

.

Note: The common properties and methods like coords.latitude and coords.longitude are used in the example below but will not be covered. Other topics not covered include calculating distance between two points, showing a location with Google Maps, and error handling. If you are not familiar with these topics please refer to our article HTML 5 Geolocation: A Practical Example.

Setting up the Scenario

We are building a new website for mountain climbers. As part of our new application we are offering a web page that will track a climber’s movement giving them up-to-date information such as their current location, distance to the mountain peak, altitude, speed and heading.

The Markup and Script

Examining clearWatch() and watchPosition()

These two methods are what allow you to begin and end watching a position. What that simply means is that watchPostiton() starts getting position data at intervals while the clearWatch() method stops a specific watchPosition() instance. The specifics of how each of these methods work is explained below.

clearWatch()

The clearWatch() method does not clear all instances of watchPosition() as you might think. Instead it stops only a specific instance. In the script excerpt below notice that we must provide clearWatch() with the ID of the instance of watchPosition() that we want to stop. If you do not provide an ID an error will be thrown.

navigator.geolocation.clearWatch(watchPositionId);

watchPosition()

This method is what kicks off the watching process. There are three different parameters that can be included to more precisely define how watchPosition() does its work. They are the name of the function that gets called each time position data is successfully obtained, the name of the function that is called when an error is encountered when retrieving position data, and finally a set of position options that further define how the method functions. Each parameter is explained below:

Success Function – This function is called each time position data is successfully retrieved. It can be any function name that you like and it is automatically sent the position object as a parameter when it is called. In our case we call function showClimberLocation(position) which handles generating our results set.

Error Function – When something goes wrong the function that you name for this parameter gets called. Like the success function, an object (specifically an error object) is automatically sent as part of the function call. The name of the function can also be anything that you like. In our case we call function showError(error) which handles displaying our error messages.

Position Options – This is a set of attributes that further defines how watchPosition() functions. Each of the attributes is explained below:

enableHighAccuracy – This lets the method know how much effort to put in on obtaining an accurate position. Setting the value to true may result in a more accurate position at the expense of additional power consumption and a slower response time. A false value will likely use less power and have a faster response time but be less accurate. Just remember that setting this attribute to true does not necessarily ensure that a more accurate position can be obtained.

maximumAge – This attribute lets the method know how long it can keep using the cached position results before trying to obtain new position data. Essentially, this allows the developer to more or less define the interval for retrieving updated positional data. This is defined in milliseconds.

timeout – This attribute simply allows the developer to define how long to wait for new position data before throwing a timeout error. This is defined in milliseconds.

An example of a watchPosition() method call using all of the parameters and attributes looks like:

navigator.geolocation.watchPosition(showClimberLocation, showError, { enableHighAccuracy: false, maximumAge: 60000, timeout: 30000 })

Examining coords.accuracy, coords.altitude, coords.altitudeAccuracy, coords.heading, coords.speed and timestamp

In the showClimberLocation function you will notice that we use all of the position properties. We have defined each of the more advanced properties here:

coords.accuracy

This property defines in meters the accuracy of the position data. What that simply means is that if the accuracy rating were 3000 you could draw a circle on a map with a radius of 3000 meters centered on the coords.latitude and coords.longitude coordinates, the actual position will be somewhere inside that circle. The bigger the number, the less accurate the coordinates.

coords.altitude

This property provides the altitude of the position in meters above or below sea level. In our example we convert this value from meters to feet.

coords.altitudeAccuracy

Like coords.accuracy, this property provides a distance in meters that reflects how far off the altitude position could be from the altitude value obtained. Again, the bigger the number, the less accurate the altitude position.

coords.heading

This property provides 360 degree heading information. A value of 0 would indicate north, a value of 90 would indicate east, a value of 225 would indicate southwest, etc.

coords.speed

This property indicates the relative speed in meters per second. In our example we have converted the meters per second value to miles per hour.

timestamp

This property indicates the date and time when the position data was retrieved. The value is in the form of a DOMTimeStamp, so you will need to use .toLocaleString() or some other method to convert the value to a readable date and time.

What to Expect

First, running this example from your computer versus a mobile device will yield very different results. Devices like modern cell phones have GPS capabilities built in and provide much better position data. In addition, mobile devices will provide much more data like speed and heading that you can’t get when using a PC.

You will also find that the browsers still have a way to go in implementing HTML 5 Geolocation. Even though all of the modern major browsers support HTML 5 Geolocation, they do not all support it fully or in the same way. In our example, you will notice that we check for both (position.coords.heading == null) and (isNaN(position.coords.heading)). The reason for this is due to different browsers assigning different values to properties when they can’t discern a value. In this case (position.coords.heading == null) is used for Opera and (isNaN(position.coords.heading)) is used for Firefox.

Lastly, expect things to change. As HTML 5 evolves, expect that implementations will get better and more consistent across the major browsers.

Conclusion

In the short term try to stick to the basics when developing using HTML 5 Geolocation. Support for getCurrentLocation(), coords.latitude, coords.longitude and coords.accuracy is fairly consistent across the major browsers, so stick with using them as much as possible for now. The other properties and methods are very interesting and useful in specific situations but will require much more planning and testing in order to get consistent results.

Happy coding!