HTML5 contains a geolocation API to find the user’s location, something that used to be accomplished by analyzing IP addresses. As shown in the specification, http://www.w3.org/TR/geolocation-API/, the API itself is fairly simple. For Windows Store apps written in HTML/CSS/JavaScript, then, there is an overlap with the Windows.Devices.Geolocation API in WinRT. So which one should you use?

Note: one key difference for any comparison with WinRT APIs is that HTML5 and native JavaScript APIs are available in the web context whereas WinRT is not. This comparison therefore only applies to pages running in the local context; in the web context you’ll want to use the HTML5/JS APIs.

It’s also helpful to note that overlaps such as these exist (a) because of the local and web contexts, and (b) to provide the capability to Windows Store apps written in other languages where an intrinsic API is not available.

With that, let’s look at both APIs in turn.

Geolocation in HTML5

HTML5′s geolocation is available through the navigator.gelocation object in JavaScript. With this you can obtain a single reading, which is useful to present location-relevant content for a visitor, and also watch the position for ongoing readings.

A single reading is retrieved through the navigator.geolocation.getCurrentPosition method, to which you pass a function that receives a position object:

navigator.geolocation.getCurrentPosition(function(position) {
     var lat = position.coords.latitude;
     var long = position.coords.longitude;
     …
});

Additional parameters to getCurrentPosition include an error function and an object containing the options enableHighAccuracy (bool), maximumAge (maximum age of cached data in milliseconds), and timeout (in milliseconds).

Ongoing (asynchronous) readings are taken by passing a callback function to navigator.geolocation.watchPosition that takes the same parameters as getCurrentPosition. watchPosition returns an ID for the operation which can be passed to clearWatch to end the readings.

The timeout option value is important as it determines the maximum length of time that can elapse between a call to getCurrentPosition and watchPosition and a callback with a position value. If that timeout is exceeded, the error function is called with a TIMEOUT error. Other error conditions are PERMISSION_DENIED (see below) and POSITION_UNAVAILABLE (no geolocation capability is available, or there’s an error in determining the location). Note that a watch will remain in place when an error occurs.

The position object passed to the callback in both cases contains a timestamp member as well as a coords object. The latter contains latitude, longitude, altitude, accuracy, altitudeAccuracy, heading, and speed (all doubles). Complete details are, of course, in the specification.

Privacy is a concern with geolocation. The W3C specification places the responsibility for insuring privacy on the agent that implements the API. Internet Explorer, for instance, pops up an alert to the user asking their permission on behalf of sites that use the API. This can be seen with the IE9 TestDrive site’s Geolocation page, http://ie.microsoft.com/testdrive/HTML5/Geolocation/Default.html.

If the user disallows geolocation, the error function given to getCurrentPosition or watchPosition is called with a PERMISSION_DENIED error.

Note that when using HTML5 geolocation in a Windows Store app (including any web content in iframes and pages within navigation domains), it is necessary to declare the Location capability in the app manifest. Without this declaration, the APIs will fail with PERMISSION_DENIED errors.

Note also that if a Windows Store app navigates to any additional websites (e.g. uses navigation domains or includes content in iframes) that utilize geolocation, it must also include the domain in the ApplicationContentUris list.

Geolocation in WinRT

In WinRT, geolocation is provided through the Windows.Devices.Geolocation API. In WinRT you create (with new) a Windows.Devices.Geolocation.Geolocator object, which you then configure with various properties if desired: desiredAccuracy (default or high), movementThreshold (double), and reportInterval (double).

Obtaining a one-time position reading is done through the getGeopositionAsync method that produces a Windows.Devices.Geolocation.Geoposition object. Its properties are civicAddress and coordinate, where the properties of the latter are accuracy, altitude, altitudeAccuracy, heading, latitude, longitude, speed, and timestamp.
var gl = new Windows.Devices.Geolocation.Geolocator();
gl.getGeopositionAsync().then(function (posOp) {
     var position = posOp.getResults();
     var lat = position.coordinate.latitude;
     var long = position.coordinate.longitude;
     …
});

A variation of getPositionAsync lets you specify maximumAge and timeout parameters.

You can also assign functions to the positionChanged and statusChanged members of the Geolocator object for ongoing readings. positionChanged will be called within the reportInterval setting, and statusChanged is called when the device status changes between the following states:

  • ready: location data is available.
  • initializing: the location provider is initializing (e.g. a GPS receiver is still acquiring satellites).
  • noData: no location data is available from any location provider (like POSITION_UNAVAILABLE in HTML5).
  • disabled: the application doesn’t have permission to access location (like PERMISSION_DENIED in HTML5).
  • notInitialized: an operation to retrieve location has not yet been initialized (i.e. the app has not called getGeopositionAsync or registered for the positionChanged event).
  • notAvailable: the Windows Sensor and Location Platform is not available on this version of Windows.

Where privacy is concerned, this API will fail unless the app has declared the Location capability in its manifest. At runtime, Windows will also prompt the user for consent.

API Differences and Distinctions

As with other overlapping parts of WinRT and HTML5/JavaScript, the Geolocation APIs in WinRT are primarily there for apps written in C++ and .NET languages, where no other option is available. For written in HTML/CSS/JS, the two alternatives are more or less equal, with a few distinctions:

  • Geolocation options: The movementThreshold option is unique to WinRT, which is used for system power management and which allows an app to only receive readings there has been enough of a change. This is helpful for geo-fencing apps that only want to update themselves when the user has moved far enough away from a given point. To do the same with the HTML5 API requires more frequent location polling and calculating distance to filter out events.
  • Position information: When address information is supported by a location provider, WinRT provides for surfacing that data through the civicAddress property (and its individual sub-propeities).

Thus, developers with existing HTML5 geolocation code, or those who want to maintain as much platform-neutral code in their apps as possible, will likely use the HTML5 API. On the other hand, the convenience of movementThreshold and its positive effect on power management is a significant benefit of the WinRT API.


One Trackback

  1. By Author news: Announcing Kraig Brockschmidt’s blog | MSDN Blogs on January 12, 2013 at 8:59 pm

    [...] For example, I have two posts thus far comparing the overlaps between HTML5 and WinRT APIs (Geolocation and base64 encryption), with others coming that address storage, XML, file, and socket APIs. A [...]

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>