Instant HTML5 Geolocation How-to: Learn how to create elegant, location-aware web applications using the JavaScript Geolocation API

The web can be accessed from different types of hardware, such as desktop computers, laptops, tablets, phones, and embedded systems.

All of this means that the web may be the most important publishing medium in the history of human civilization—a medium that anyone can publish to and consume. However, because each device has slightly different capabilities, each feature may have slightly different characteristics from user to user. For example, in HTML5, some web browsers can play certain video formats, while other web browsers can play other video formats. In the Geolocation API, these changes relate to how location is computed, and as a result, how accurate it is.

Here's how the Geolocation API works from the user's perspective. You can see it in action by visiting my demo at http://benwerd.com/lab/geo.php.

Your application needs the Geolocation API if:

Your application cannot use the Geolocation API if:

We will discuss why in the next section.

The request for information is an important step to protect user privacy. The Geolocation API specification explicitly states, "User Agents must not send location information to Web sites without the express permission of the user." It's sadly true that the user's location can often still be determined without his/her consent through other means, such as IP geolocation or by sharing data between applications. However, these are unrelated to the Geolocation API, and we will not be discussing them here.

Here's what a location request looks like when using Google Chrome on my MacBook Pro using a home broadband Internet connection:

Note the ribbon above the main web page content. The entire content of the page has been sent to the browser; once location information has been sent, JavaScript could change the content of the page (for example, using the jQuery framework), submit the content elsewhere using a callback, or forward the browser to another page.

Here's what it looks like in the Android Chrome browser:

You can test your browser's geolocation capabilities by visiting http://benwerd.com/lab/geo.php.

Here's what it looks like when using Google Chrome on my MacBook Pro using cable Internet:

Here you can see that although my latitude and longitude have been calculated reasonably accurately, my altitude, heading, and speed details are not available. This is because these details are determined using GPS (Global Positioning System) technology, and my laptop does not have this capability. Instead, my web browser needs to guess my location based on various environmental factors.

Here's what the same Geolocation API test looks like on my Android Chrome browser on my cell phone:

You might be surprised to see that my altitude, heading, and speed information is still not present, despite having been determined on a cellphone that has hardware GPS support. In fact, this is because (if you use the default Geolocation API configuration) Chrome on Android attempts to use WiFi location first, where it's available, before resorting to the relatively battery-intensive (but more accurate) GPS location.

Here's what the test page looks like on an iPad:

Because the iPad did use GPS data to determine my location, altitude information is available. However, I wasn't moving, so there's no speed or heading information.

Only latitude, longitude, and accuracy are guaranteed to be there. The other fields are entirely dependent on the user's device, movement, and location context.

Where GPS is not available, the browser will use a process called trilateration to determine the location.

All modern browsers across both desktop and mobile platforms, except for Opera Mini, support the Geolocation API. Most have done so for enough time that you should be comfortable using the API in your web applications.

(Source: CanIUse.com)

It's worth noting that because Microsoft Internet Explorer 9.0 was the first version to not support Windows XP, there remains a significant enterprise userbase—Internet Explorer users with Windows XP operating systems—that cannot use applications based on the Geolocation API. At the time of writing, this represents 24 percent of all web users worldwide according to theie8countdown.com. For this and a host of other reasons, including their own security, let's hope that they will upgrade soon.

The lack of Opera Mini support also means that many mobile phone users, particularly in developing nations or users with feature phones, are not able to use the Geolocation API. This situation is likely to change soon, as open source mobile operating systems such as Android and Firefox OS are gaining traction in those markets.

There are four core actions that will need to be supported:

For the purposes of this book, we will support them in turn with:

Note that you could use any web browser, any web scripting language, and virtually any database, to perform these tasks. I hope that the examples here are generalized enough to allow you to translate them into the languages and server software of your choice. For example, if PHP isn't to your taste, these examples should be relatively easy to translate into Ruby or Python.

We will assume that you are running a recent copy of Apache Web Server, configured to allow scripting using PHP 5.3 or later.

Create the following files in a new location on your web server:

Create a new MySQL database table (and, if you like, a new database to house it in) for this example. This will store our retrieved geolocation coordinates, with a timestamp and an identifier for the user.

There are a number of different ways we could store the location information. Geolocation coordinates are returned as longitude and latitude; an angle on the surface of the Earth east and west of the Prime Meridian, and an angle north and south of the Equator, respectively. Recall the example data in the Understanding the geolocation API (Simple) recipe, the angles were returned to 14 decimal places. The more accurately we can store these numbers, the more accurately we can retrieve the user's location.

For the purposes of this tutorial, we are going to store our coordinates as a set of floating point numbers. This is because we're not performing any comparisons on the geographic data; we're simply storing and retrieving it.

All we need, then, is decimal point latitudes and longitudes with the required level of accuracy, as well as an integer identifier for the user, and another for the timestamp. As we'll be searching by user and timestamp, it's a good idea to maintain an index for each of these fields.

We'll call our database table points:

--
Table structure for table 'points'
--

CREATE TABLE IF NOT EXISTS 'points' (
'id' int(11) NOT NULL AUTO_INCREMENT COMMENT 'Our primary index field',
'latitude' float NOT NULL COMMENT 'Our latitude coordinate',
'longitude' float NOT NULL COMMENT 'Our longitude coordinate',
'user_id' int(11) NOT NULL COMMENT 'The unique ID of the user',
'time' int(11) NOT NULL COMMENT 'The UNIX timestamp of the time when the point was recorded',
PRIMARY KEY ('id'),
KEY 'user_id' ('user_id'),
KEY 'time' ('time')
) ENGINE=InnoDB;

Note that I've also included a unique identifier for each row in the database, for ease of access later.

One of the problems with geographic data is that it's very easy to store a huge amount of it, which can cause databases to slow down if you're not careful—particularly, if you're doing a lot of proximity queries, for example, to discover stored geographic points within a certain radius of a location. The mathematics behind this functionality, while not massively complicated, can become expensive in aggregate.

MySQL has a spatial support extension, which allows you to store, retrieve, and compare extensions based on an optimized geographic engine. This uses a standard set from the OpenGIS project to store sets of geographic data. It's often installed by default, and is worth getting to know for more sophisticated geo-aware applications.

Make sure you've set up the required files in the previous section: index.php to serve the main page, callback.php to serve as our callback, and feed.php to serve as our KML feed. In this section, we will be concentrating on index.php and callback.php.

Perform the following steps for getting the user's location:

There are two large JavaScript blocks in index.php, which together interact with the Geolocation API. In the body of the page, we've included a simple div element with ID locationpane, which we'll use to give feedback to the user. Every time we give feedback, we do so by changing the HTML contents of locationpane to contain a paragraph with a different message.

In the header of the page, there are two functions: savePosition and errorPosition. savePosition will be called by the Geolocation API when a location is determined and errorPosition will be called when there has been an error determining the location.

savePosition takes a single Position object as its first parameter. This has the following properties:

Note that on some systems in certain contexts, the location won't be determined at the time of request; instead, a cached version will be returned. This is why the timestamp is important. However, we will discard it here.

savePosition uses jQuery's AJAX function to take the latitude and longitude from the coords object and sends it to callback.php. It then checks the HTTP response code; if callback.php has returned an error 500, it tells the user that his/her location could not be saved. (More on this in a moment.)

Meanwhile, if there was an error determining the user's location with the Geolocation API, errorPosition is called. This takes a PositionError object as its parameter, which has the following properties:

Rather than output message, which isn't intended for end users, errorPosition looks at the error code to determine what kind of feedback to provide to the user:

At the bottom of the page is the code that actually runs the Geolocation API.

Before accessing the JavaScript API functions, it's important to check to make sure that the Geolocation API is supported in the current browser. To do this, you can simply check to make sure the navigator.geolocation object exists:

if (navigator.geolocation) { /* The Geolocation API is supported */ }

If it doesn't, we should give the user feedback to explain that his/her location cannot be determined. We could also attempt to retrieve the user's location using server-side technologies such as IP geolocation, but this is much less accurate and out of the scope of this book.

Once we're sure, we can use the Geolocation API, we can call navigator.geolocation.getCurrentPosition, with references to the success and failure functions as its parameters:

navigator.geolocation.getCurrentPosition(savePosition, errorPosition);

It's worth mentioning here that a third parameter is available, which takes a PositionOptions object. This may contain the following properties:

If we enable high accuracy mode, mobile devices with GPS units will attempt to use it to get the best possible location information (if their owner has allowed it); otherwise, they may default to using trilateration to determine the location. However, because not all devices have these units and because GPS signals are not always available, requesting the current position with high accuracy is more likely to fail.

While high accuracy, location detection will not automatically fall back to the standard method, you can achieve this yourself, if you like. First, call getCurrentPosition with highAccuracy set to true and with a reference to a new error handling function:

navigator.geolocation.getCurrentPosition(savePosition, highAccuracyErrorPosition, {enableHighAccuracy: true});

All this new error handler, highAccuracyErrorPosition, does is call getCurrentPosition with highAccuracy set to false:

function highAccuracyErrorPosition(error) {

navigator.geolocation.getCurrentPosition(savePosition, errorPosition, {enableHighAccuracy: false});

}

The result is that the browser attempts to use high-accuracy location detection, and falls back to the standard method if it is not available due to some reason. Should the user decline authorization for location information, this continues to be respected down the chain.

The callback script, callback.php, first loads the database functionality from lib.php and ensures that it can connect. If connection fails for some reason, it returns an HTTP error 500 (Internal Server Error), which tells index.php to display an error to the user, as previously described.

If callback.php is connected to the database successfully, it then sanitizes the input variables, latitude and longitude. It's important to make sure both are cast to floating point variables, to minimize the risk of SQL injection attacks. The script also retrieves the current UNIX epoch timestamp (represented as the number of seconds since 00:00 on January 1, 1970).

The script makes it possible to store location information for an unlimited number of users. However, because authentication and user handling are not within the scope for this book, we've hardcoded the user's unique ID to 1. If you had a separate MySQL user table, for example, you would set this value to the ID of the currently logged-in user. This ID would be saved in the current browser session at the point of login. callback.php would use the version saved in the session rather than sent to it explicitly via a GET or POST variable, to prevent third parties from maliciously saving location information to a user's account.

Finally, callback.php attempts to save this data to the MySQL table we created in the previous section, using a standard MySQL insert call:

$query =    "insert into points set 'longitude' = {$longitude}, 
    'latitude' = {$latitude},
    'user_id' = {$user},
    'time' = {$time}";

Once again, if an error occurs, the script returns an HTTP 500 error so that the JavaScript on index.php can let the user know in a friendly way.

Otherwise, we can reasonably assume that the data was saved in our MySQL table. Because we saved it with timestamp information, and because we are also saving the user's unique ID in the same table row, we will be able to easily retrieve any individual user's locations in chronological order later on.

PHP's default HTTP response code is 200: OK. This tells the jQuery call in index.php that the positioning data was saved without any problems. In turn, index.php lets the user know that his/her location was saved.

Let's begin by retrieving all of our previously-saved points.

To display our location data, we will use a MySQL function stored in lib.php to retrieve existing map points. We will also load the Google Maps API using Google's hosted JavaScript library and make use of the following Google Maps objects:

There are three main structural changes we must make to index.php. First, we must require that lib.php is loaded. This will give us access to the database and a new function that we'll add to that library.

So far, we've only stored geolocation data; we haven't displayed it to the user at all. However, because we've been saving it to the database, we potentially have a rich history of location data that we can retrieve—organized by both user and time. A new function, getPreviousLocations($user_id), returns this data as an array in chronological order using a simple MySQL select call:

$query = "select 'latitude', 'longitude', 'time' from 'points' where user_id = $user_id order by 'time' asc";

Recall that for the purposes of this tutorial, we're always setting $user_id to 1. A more sophisticated application would substitute a user identifier from the current browser session, or another location.

By requiring lib.php at the top of index.php, we can ensure that we have reliable access to this information from the database:

<?php 
// Load our common library file, and fail if it isn't present
require_once('lib.php');
?>

Another new addition is the JavaScript library that Google provides for the Google Maps API. Note that by omitting the URI scheme (http: or https:), we can ensure that the browser will use the correct one, whether your page is accessed over a standard or secure HTTP connection. This is placed within the HTML <head> tag in index.php:

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=true"></script>

Finally, we also need a place on the page to display our map. For this, we establish a new, empty div element with a unique ID (here I've used map_pane). The Google Maps API will populate this with a complete map later.

Now that we've set up the framework of the page, we can begin configuring the map. We do this in the JavaScript block at the bottom of the page:

// Set initial viewing options for the map
var mapOptions = {
  zoom: 15,
  mapTypeId: google.maps.MapTypeId.HYBRID
};

The zoom level for Google Maps starts at 0, where you can see the entire globe. Theoretically, the zoom levels are infinite, but in practice, for most maps, the maximum level is 19. Set the zoom level at 15; it's close enough to be able to view your location with precision, but zoomed out enough to see a large amount of the surrounding neighborhood.

There are a number of different map types at your disposal:

For now, set the mapTypeId to googlemaps.MapTypeId.HYBRID.

Next, initialize the Map object with the options you've just defined, and the map_pane DOM element. This is enough to display the map inside the map_pane div. We'll save it to the window.googleMap global variable, which will come in handy.

window.googleMap = new google.maps.Map(document.getElementById('map_pane'), mapOptions);

However, there's every chance we've already got some location information to display. Here's where our PHP function, getPreviousLocations($user_id), becomes useful. Recall that it's returning an array of database row objects containing latitude, longitude, and time.

JavaScript is a front-end language, interpreted in the web browser; PHP is a server-side language, interpreted before any HTML is received by the browser. They cannot directly interface with each other. As a result, we need a way to pre-process the array of coordinates so that it's readable by JavaScript. JSON is perfect for this task.

Luckily, PHP provides a very simple function to encode PHP variables as JSON: json_encode. We just need to use this on the result of getPreviousLocations($user_id). Remembering that we're hardcoding the value 1 in place of $user_id, our hybrid JavaScript/PHP code looks like the following:

var jsonPoints = <?=json_encode(getPreviousLocations(1));?>;

If there was a single location point in the database, this might be rendered as follows:

var jsonPoints = [{"latitude":"37.7595","longitude":"-122.463","time":"1362975429"}];

In other words, jsonPoints is seen by JavaScript as an array of JavaScript objects. We can simply check that the array is non-empty, and iterate through any elements using the Array.forEach method:

if (jsonPoints.length > 0) {
  window.points = new Array();
  jsonPoints.forEach(function(point) {
    window.points.push(new google.maps.Marker({
      position: new google.maps.LatLng(point.latitude, 
      point.longitude),
      map: window.googleMap
    }))
  });
}  

We establish window.points as a global JavaScript array of Marker objects, the objects used to represent individual geographic points in the Google Maps API. On instantiation, Marker objects are given a position in terms of a LatLng object containing latitude and longitude, and a reference to the Google Map that will display them. (We can simply supply the window.googleMap variable we created earlier for this purpose.)

Once the previously saved geographic points have been written to the map, we must ensure that the newly detected location, if it has been successfully obtained, is also added.

Previously, we had written a message to the screen—Location saved—once a location had been successfully processed. Now, we need to also draw it to the map.

First, we create a new LatLng object containing the latitude and longitude of the newly saved location:

var currentLocation = new google.maps.LatLng(window.latitude, window.longitude);

Next, we can center the map on it using the Map object's setCenter method:

window.googleMap.setCenter(currentLocation);

Finally, we create a new Marker object, containing a simple title, the newly created LatLng object, and a reference to our Map:

var marker = new google.maps.Marker({
  position: currentLocation,
  map: window.googleMap,
  title: 'Current location'
});

The location appears as a pin on the map, alongside previously saved locations.

Perform the following steps:

Perform the following steps to display the user's location using a KML feed:

It's not a good idea to hand-code an XML-based file, or to use a static template to do so. Various tools and libraries are available, and the DOM extension that was introduced with PHP 5 is an easy way to get started.

Our KML file consists of a Document node, which in turn contains a series of Placemark nodes. We could include a large amount of data here, but our minimum viable KML file will list name, timestamp, and geographic point information inside each Placemark. These are contained within name, TimeStamp, and Point nodes respectively. The Point node in turn contains a coordinates node, which lists the geographic coordinates of the point. Note that KML coordinates list the latitude first, followed by a comma, followed by the longitude. Spaces should not be used.

Placemarks can include more than one Point, as well as a selection of other geographic elements, but for the purposes of this example, we'll stick to one Point per Placemark.

TimeStamps are listed in ISO 8601 format. The TimeStamp for 7:30 p.m. Pacific Time on March 11, 2013 would appear as follows:

Mon, 11 Mar 2013 19:30:00 -0700

Create a new XML file in PHP by instantiating a DOMDocument object, specifying XML Version 1.0 and the UTF-8 character set:

$feed = new DOMDocument('1.0','UTF-8');

Define it as being a KML file by including the KML namespace, and establishing a root node:

$rootNode = $feed->appendChild($feed->createElementNS('http://earth.google.com/kml/2.2', 'kml'));

New child nodes are added to a DOMDocument through use of the appendChild method; elements are created inside them using createElement. Now you have your root node, you can add the Document node:

$documentNode = $rootNode->appendChild($feed->createElement('Document'));

Using the getPreviousLocations function we created earlier, we can nest a series of Placemark nodes with the features as described in the preceding code line, using more calls to appendChild and createElement. The complete code is available in feed.php for you to peruse.

All of your data is now loaded into the feed. All that's left is to write it to the browser. First, you must tell it that this is an XML file, by setting the HTTP header appropriately:

header('Content-type: text/xml');

Finally, then, you can write it to the browser:

echo $feed->saveXML();

This is all you need to create a fully functional KML feed. There's much more available in the KML specification, including details about how to style map points, and other information that can be included inside the feed as a whole, as well as each individual Placemark. A link to the KML specification is included at the end of this section.

Because Google Maps natively supports KML, once you've made your system live on the web, you can simply paste the URL to your feed.php file into the Google Maps search box, and your geographic points will be displayed.

Additionally, you can choose to load your KML file into the map you created in index.php. This has the same effect as entering the address of your KML file into the Google Maps search bar, but on the map embedded in your own application.

You may remember that we created a global variable referencing the map called window.googleMap. Directly underneath, you can create a KmlLayer object as follows:

window.kmlLayer = new google.maps.KmlLayer('http://your/kml/feed.php');
window.kmlLayer.setMap(window.googleMap);

Of course, http://your/kml/feed.php must be replaced with the URL of your feed.

This section doesn't require any PHP programming; the modifications are all on the front end, using JavaScript. However, ensure that you have a compatible device with a GPS receiver and mobile data capability available to test your code. Most modern smartphones should suffice; we tested with the Chrome browser on a Samsung Galaxy S2, and in Safari on an iPhone 5.

Perform the following steps to track and update the user's location:

The Geolocation API watchPosition method uses a very similar syntax to the getCurrentPosition method we used earlier. Its parameters are the same:

The available options, in turn, are also the same:

However, rather than initiating a single check for the user's location, it instead establishes a "watch" that will load the callback functions as appropriate whenever the device has detected that the user has moved. Because you need to reference the watch process, watchPosition returns an identifier.

The identifier is obtained when the method is called, as follows:

window.watchLocationID = navigator.geolocation.watchPosition(savePosition, errorPosition, {enableHighAccuracy: true});

Note that we've used the enableHighAccuracy option, while not failing back to a lower-accuracy location method. That's because in a situation where you're continually retrieving the location, low-quality data will not be useful. Because the device falls back to estimating location through environmental factors, visibly erroneous data may be included in your dataset, sometimes hundreds of meters or more away from the user's actual location, making it harder to track the user's path. It's better to fail if a GPS signal cannot be found.

Sometimes, the user may wish to switch tracking off, while remaining on the page. To do this, we've created a simple button. This will trigger the clearWatch method, which takes the watch process ID as a single parameter as follows:

navigator.geolocation.clearWatch(window.watchLocationID);

In our implementation, we've also hidden the button using the jQuery hide() method once it has been pressed.

Finally, our savePosition function, which is called whenever a new location is successfully received, must display the new location.

In our previous implementation, we simply created a variable for the new Marker object to display a single point. However, we also created a window.points array to keep the Marker objects that were reloaded from the database. In order to display the full set of points that are displayed as the user moves around, we'll need to add each newly created Marker in the array too.

To do this, we can just push new Marker objects to the array as follows:

window.points.push(new google.maps.Marker({
  position: currentLocation,
  map: window.googleMap,
  title: 'Detected location'
}));

However, a series of individual points isn't necessarily the best way to display this data.

Unfortunately, at the time of writing this book, there's no way to prevent the mobile device from switching its screen and GPS unit off. Consider the following screenshot from a walk I took around the Inner Sunset neighborhood in San Francisco:

Contrary to what the map might indicate, this was a continuous walk—I didn't suddenly leap two blocks in a single bound! However, while I was holding my device and ensuring that its screen didn't turn black on some of the streets (indicated by the vertical lines you can see here), on the others I chose to slip my device into my pocket, as an ordinary user might. The GPS receiver was deactivated automatically when the screen went black, in order to conserve battery life. As a result, no location points were saved for these portions of my journey.

We can further enhance our application by replacing the individual points on the map with a continuous line. This would also help smooth over any gaps in the dataset.

To achieve this, we need to replace the portions of the code that set points on the map using the Google Maps API. Google provides another element, PolyLines, which allows you to arbitrarily add coordinates to a continuous line. I've included the complete code as livepath.php.

In the portion of the page where we're setting up the map, just after we've loaded the jsonPoints JSON array, we need to create a polyline. We'll make it bright red (HTML color #ff0000) so that we can see it easily:

window.polyLine = new google.maps.Polyline({
  strokeColor: '#ff0000',
  strokeOpacity: 1.0,
  strokeWeight: 3
});

Now, we'll attach it to our existing map. window.polyLine will be the global variable that stores the polyline:

window.polyLine.setMap(window.googleMap);

And finally, we'll establish window.geopath as the array of points that make up the polyline. We're saving that as a global variable too, for convenience. You'll see why momentarily.

window.geopath = window.polyLine.getPath();

Now, let's load our JSON array of previously saved points onto it:

// If jsonPoints isn't empty, iterate through and create new map 
// points for each geolocation point
if (jsonPoints.length > 0) {
  jsonPoints.forEach(function(point) {
    window.geopath.push(new google.maps.LatLng
    (
      point.latitude, point.longitude
    ))
  });
}

Finally, recall the AJAX done() function at the top of the page, which is called once a new location has been successfully processed. We can replace the Google Maps code in this function with a simple line to add the latest coordinates to our PolyLine:

// Create a marker at the user's current location and save it
// to our array of map points
window.geopath.push(new google.maps.LatLng(window.latitude, window.longitude));

Now, whenever a new location is detected, it will be added to the line rather than to the map as a new, individual point.

The Geolocation API is an important addition to any modern web developer's arsenal. Together with other new APIs, HTML 5 itself and the new breed of mobile devices, the web doesn't just allow you to build high quality network applications; it allows you to build new kinds of context-aware applications that have never been created before. Happy building.