Background

Introduction

With the emerging HTML5 standard, it is now possible to do many things from JavaScript in the web browser which previously could only be done within standalone applications. You have already seen one example in the canvas tag, which can be used to develop real-time 2D graphics applications in the browser. Today we will be looking at another, the Geolocation API (not strictly part of HTML5 but generally grouped with it)

The Geolocation API allows you to obtain the current location of the device running the browser from within JavaScript. Even on desktop browsers this will give a result if you are using a wireless network, but its real use is in the mobile web development world. A mobile browser can talk to the GPS chip of the phone and obtain the phone's current location on the earth. Alternatively, if the GPS chip is not available, a rough estimate can be obtained from cell towers or wireless networks.

Latitude and Longitude

In order to understand location-based applications, it is important to understand the coordinate system used on the earth. The most common coordinate system uses latitude and longitude. Latitude is a measure of how far north or south you are: the equator is at 0 degrees, while the North Pole is at 90 degrees North, we are at about 50 and Spain is at about 40. Longitude is a measure of how far east or west you are: 0 degrees of longitude is referred to as the Greenwich Meridian and passes through Greenwich, London. By contrast Germany is located between approximately 7 degrees and 15 degrees East, while New York is at 74 degrees West and the west coast of North America at approximately 120 degrees West.

So a given point on the earth can be defined via its latitude and longitude. We are at, approximately, 50.9 North (latitude) and 1.4 West (longitude). By convention, latitudes north of the equator and longitudes east of Greenwich are treated as positive, so we can also define our position as longitude -1.4, latitude +50.9.

Using the Geolocation API

It is fairly straightforward to use the Geolocation API. Here is an example:

Geolocation Test



]]>

How is this working?

• When the page first loads, the init() function runs. This tests whether geolocation is possible in our browser by checking for the existence of the navigator.geolocation variable. If it doesn't exist, we display an error. If it does exist, we tell the geolocation object to obtain the current position with getCurrentPosition(). This takes two parameters, both functions:
  • The first (here, processPosition()) is the function that will run as soon as we get a location back from the GPS chip (or wireless network, etc)
  • The second (here, handleError()) will run if there was an error obtaining the location.
• Note the asynchronous approach here, just like AJAX. It might take time to obtain a position, so we set up a callback function to run once we have obtained the position, and continue processing in the meantime. So any statements below the getCurrentPosition() might run before the callback processPosition() starts running.
• Considering each of these two functions in turn, let's look at processPosition() first. This is automatically supplied with one parameter, pos, representing the position returned from the GPS device or other location provider. We can obtain the latitude and longitude with pos.coords.latitude and pos.coords.longitude. So what this example is doing is placing the coordinates inside the <div> with the ID of info.
• Moving onto handleError() which is the function which is run if there is any sort of error in obtaining the position: again, this is automatically supplied with one parameter, err, representing the exact error which occurred. The most meaningful property of err is a numerical code, err.code, which is what we are displaying here. There are several codes (ref Dive into HTML5, Mark Pilgrim):
  • 1 means that the user denied the browser access to the device's location. For security reasons, a user has to agree to the browser accessing the device's GPS chip, and if they deny that access, the error function will run with a code of 1.
  • 2 means that the location could not be obtained, e.g the GPS satellites or wireless networks are unavailable;
  • 3 means a timeout, i.e. the GPS satellites or network are available but it has taken too long to contact them.

Watching the position

The above code will simply obtain the current position and stop. In a typical mobile GPS application, however, the user will want to be informed of their location on a regular basis. To do this we use watchPosition() in place of getCurrentPosition(). Here is an example:

Geolocation Test - Watching Position



]]>

Note that the code is almost the same as the first example, except:

• We use watchPosition() rather than getCurrentLocation(). The result will be that the GPS chip (or other location provider) will communicate the current location back to processPosition() every time the location changes, rather than just the once.
• Note also the additional options passed as a third parameter to watchPosition(). On many mobile devices, if we want to use the GPS chip (rather than cell towers, wireless networks, etc) we have to set the enableHighAccuracy option to true. Also if we want to force the GPS to return a reading every so-many seconds, we have to specify a value for the maximumAge option, in milliseconds. So the above example will refresh at least every 5 seconds.

Obtaining direction and speed of travel

As well as the position, a number of other properties are available to us. These include the direction we are heading (measured in degrees) and the speed of travel (measured in metres per second). To obtain these we use the heading and speed properties of the position object passed into our location-updating function (i.e. processPosition() in the above example). So in the example above we would reference the direction with pos.coords.heading and the speed with pos.coords.speed. Note that these are calculated from the previous GPS position.

Exercises

1. Try out the first example above to see the Geolocation API working.
2. You now have a choice between the following exercises.
   • Further Geolocation exercises requiring a smartphone and your own server space. See below.
   • If you do not have a smartphone, try this exercise using the Geolocation API. On Edward is a script to look up points of interest by latitude and longitude (see below). Use AJAX to look up all points of interest near your current location. Since the university PCs can get a reasonably accurate location using the wifi network, this is something you can do without a smartphone or your own server space. To do this, make an AJAX request to:

     	http://edward/ewt/poi.php?lon=[your longitude]&lat=[your latitude]
     	

     (This script queries a database containing points of interest taken from OpenStreetMap, data copyright OpenStreetMap contributors, licenced under Creative Commons Attribution-ShareAlike Licence 2.0.)
     
     Try running it in the browser to get an idea of the format of XML returned, and then parse the XML using the DOM.
   • Allow the user to filter points of interest by type (use a select box)

Exercises requiring a smartphone

These exercises require a smartphone to test (e.g. iPhone 3.0+; Android 2.0+; recent Nokia smartphones). Also, because Edward is not externally accessible, you will not be able to test them on Edward. So, you will need to upload them to your own server space if you have it (for example, the PHPFog cloud space from last week)

• Extend the watchPosition() example (the second example above) so that the speed and direction are also shown. Test on your GPS-enabled smartphone if you have one (should work on Android 2.0+ or iPhone 3.0+)
• Show the speed in kilometres per hour, rather than metres per second. (1km=1000m; 1hr=3600sec)

Advanced exercises

For students comfortable with programming only!

1. A pedometer is a device which keeps track of how far you have walked. Develop a simple pedometer using the Geolocation API. Every time a new location is received, calculate the distance travelled. The position object (the pos parameter to processPosition(), above) has an additional property timestamp (milliseconds since Jan 1st 1970). Save this in a global variable (i.e. a variable declared outside your functions) every time processPosition() runs. Then, next time processPosition() runs, we can calculate the time passed since the last call by subtracting the previous time from the current time. This then allows us to can calculate the distance as we have both the time passed and the average speed over that timespan. The distance in metres will be speed*(time/1000), with speed in m/s and time in milliseconds. Each time the location updates, add the distance travelled since the last update to a global variable and show that on the browser (in km)
2. (Knowledge of basic trigonometry required) Using canvas, draw a graphical compass display, showing a circle containing a compass needle pointing in the current direction of movement.