Introduction to the Geolocation API

Article
03/03/2016

This topic provides an introduction to the Geolocation API, explains how to determine if Geolocation is supported, and discusses how user privacy is protected.

Introduction

Windows Internet Explorer 9 introduces a built-in location provider that uses Wi-Fi location data and Internet Protocol (IP) address information to determine the latitude and longitude of the computer or device running Windows Internet Explorer. The Geolocation API exposes the latitude and longitude to JavaScript in a webpage by using the geolocation object, which is a child object of the window.navigator. The geolocation object enables a webpage to do the following:

Get the current geographic position by using the getCurrentPosition method.
Watch the position as it changes over time, by using the watchPosition method. A call to watchPosition has the effect of subscribing to continuing location updates, until clearWatch is called to stop watching for changes.

Both of these methods return immediately when they are called. The result of the method call arrives asynchronously - each of these methods take an argument for a callback method you implement to receive the location when it is determined.

A simple call to getCurrentPosition, without detection or error checking, might look like the following line of code:

  window.navigator.geolocation.getCurrentPosition(show_map);

The show_map callback function receives the latitude and longitude coordinates.

  function show_map(position) { 
    var latitude = position.coords.latitude;
    var longitude = position.coords.longitude;
    // Add code to show a map here
  }

For sample webpages that demonstrate how to display location in more detail, see:

Detecting Geolocation Support

Before you use the Geolocation API, your application should check whether the browser supports it. If the Geolocation API is not available, window.navigator.geolocation will be null. The following code example checks whether or not the Geolocation API is available. When the user clicks a button, a function displays an alert box that indicates whether geolocation is supported.

<!DOCTYPE html>

<html>
<head>
  <title>Geolocation example: Checking for geolocation support</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge"> <!-- Remove this line in production. -->
</head>

<body>
  <p>
    <input type="button" onclick="show_islocationenabled();" value="Is Geolocation supported?" />
  </p>
  <div></div>
  <script>
    function show_islocationenabled() {
      var str = "No, geolocation is not supported.";

      if (window.navigator.geolocation) {
        str = "Yes, geolocation is supported.";
      }

      document.getElementsByTagName('div')[0].textContent = str;
    }
  </script>
</body>
</html>

In the preceding example, the <!DOCTYPE html> element at the top of the page is actually required. The Geolocation API is an implementation of the emerging standards set forth in the W3C Geolocation API Specification, and Internet Explorer only supports the Geolocation API in webpages displayed in IE9 Standards mode and higher. To enable Standards mode for Internet Explorer 9 and later versions, include the <!doctype> directive that declares an HTML5 document type.

<!DOCTYPE html>

Considering Privacy

Privacy is an obvious concern when sharing physical location with a remote web server. Therefore, the Geolocation API requires users to provide permission for the web application to access location information. The first time a webpage that requests geolocation data is visited, Internet Explorer displays a notification bar to prompt for access to the user’s location. A call to getCurrentPosition or watchPosition triggers the prompt.

The prompt gives the user the following options:

Allow one time. The notification bar will be displayed again the next time the user visits the site.
Always allow, or always deny. Internet Explorer remembers the user's choice so that the notification bar won't be displayed again.

The notification blocks until the user makes a choice, so there is no chance of the website determining location while waiting for the user's response.

If the user does not grant permission, location information will not be available to the web application. Calls to getCurrentPosition and watchPosition do not trigger a success callback. If an error callback is provided, it will be triggered with an error code of PERMISSION_DENIED.

Developers of web applications that collect location data should consider the following guidelines for privacy:

Request location information only when necessary, and use the location information only for the task for which it was provided.
Dispose of location information when the task for which it was provided is complete, unless explicitly permitted to store it by the user.
If location information is stored on a web server, make sure to protect location information from unauthorized access, and allow users to update and delete this information.
Disclose the fact that the application is collecting location data. This disclosure must include an explanation of any exceptions to the guidelines listed above.