Approximate Geolocation Explainer

A proposal to add approximate location to Geolocation API.

Motivation

The web platform currently allows websites to request precise geolocation data, which users can decide to share or not with the website. For many use cases, an approximate location would be sufficient, yet websites have no way to signal it. In other cases, even if the website can offer a more accurate experience when knowing the user's precise location, the user might want to only share their approximate location with the website, but currently does not have the possibility to do so.

Mobile operating systems already provide APIs and user controls for approximate location:

• iOS 14 introduced a Precise Location app setting which may be turned off to use approximate location. When precise location is off, the app receives an approximate location estimate with accuracy between 2 kilometers and 10 kilometers based on the population density of the user's location.
• On Android 12 and later, users choose to grant approximate or precise location permissions. When an app has the approximate location permission and not the precise location permission, it receives an approximate location estimate with a minimum accuracy of 2 kilometers.

Proposal

We propose to expose to websites the concepts of approximate and precise location.

Permission Prompt and UI. While this explainer does not go into the details of how the permission prompt and permission settings for geolocation should or could be updated to support approximate geolocation, when prompting for geolocation user agents should allow the user to choose between precise and approximate geolocation.

Generate approximate location data. To generate an approximate position estimate, the browser should use the platform's approximate location source if available, but may acquire a precise position estimate and apply a coarsening algorithm otherwise. The coarsening algorithm should make it difficult to infer the user's precise location from an approximate position estimate.

As an example of a coarsening algorithm, see LocationFudger which is used by the platform location API on Android. This algorithm uses two techniques: snap-to-grid and random offsets. Snap-to-grid creates a many-to-one mapping of precise locations to approximate locations within a local area. Because of the random offsets, simply crossing a grid boundary does not automatically allow to inferred precise location data.

Request approximate location. When calling getCurrentPosition or watchPosition, the caller may pass a parameter to request approximate location mode. If the caller requests approximate location mode it must only receive approximate location data.

Example

navigator.geolocation.getCurrentPosition(
    onsuccess, onerror, {accuracyMode: 'approximate'});

Potential specification changes

Introduction

The introduction will be updated to introduce the concepts of precise and approximate location and define the accuracy bound for precise location.

PositionOptions dictionary

Section 7 defines the PositionOptions dictionary. Callers of getCurrentPosition and watchPosition can pass a PositionOptions parameter to modify the position request.

dictionary PositionOptions {
  boolean enableHighAccuracy = false;
  [Clamp] unsigned long timeout = 0xFFFFFFFF;
  [Clamp] unsigned long maximumAge = 0;

  // New
  AccuracyMode accuracyMode = "precise";
};

enum AccuracyMode {
  // Request precise location.
  "precise",

  // Require approximate location.
  "approximate"
}

PositionOptions will be extended to add an accuracyMode member. Callers can pass "approximate" to request approximate location or "precise" to request precise location. If accuracyMode is not set, it defaults to "precise" (for backwards compatibility, so that we do not break existing use cases).

Exposing Accuracy Level in GeolocationPosition

Although we initially considered exposing the accuracy mode in the returned GeolocationPosition, it was eventually decided not to do so. In this way, the user choice (approximate/precise) is not exposed to the website. The website can still rely, for its functionality, on the accuracy of the returned GeolocationCoordinates, which can be higher or lower for a number of possible reasons. This now includes the possibility that the user only granted approximate geolocation access.

Capability detection

Support for approximate location can be detected with the following code:

function browserImplementsAccuracyMode() {
  try {
    navigator.geolocation.getCurrentPosition(
      () => {},
      () => {},
      {
        get accuracyMode() { throw new Error('1'); },
        get enableHighAccuracy() { throw new Error('2'); }
      }
    );
  } catch (e) {
    if (e.message === '1') {
      return true;
    }
    console.assert(e.message === '2');
    return false;
  }
  console.assert(false, 'this code will never be reached');
}

Permissions

Section 3.1 defines a powerful feature "geolocation". When a site uses the Geolocation API, the user should have full control not only over the binary choice of granting or not granting location access, but also over the granted accuracy.

Hence we propose to adapt the Request a position algorithm, so that:

• if the website requests precise location, the user is prompted to choose with the two approximate/precise options.

• if the website only requests approximate location, the user is only prompted to grant approximate location access.

Note that the Permissions specification does not go into details about how the user agent should internally store the user's choice. In any case, that choice is not exposed to the website, and the permissions.query() API still only exposes one value for the "geolocation" permission, returning "granted" if location with any accuracy is granted.

The Permissions specification is also intentionally vague about the specific UI to display when prompting the user to choose between different options, and leaves freedom to the user agent in this regard.

It must always be possible for the user to revoke the permission granted to a website or change its granularity at a later point in time.

Permissions policy

Section 11. defines a policy-controlled feature "geolocation". It will be updated to define an additional policy-controlled feature "geolocation-approximate", also with a default value of "self", that will only allow approximate location. The "geolocation" feature will imply the "geolocation-approximate" feature.

Request a position

In Section 6.5, the request a position algorithm requests permission to use "geolocation". It will be updated to allow for three different prompt cases:

1. If the website doesn't set accuracyMode="approximate", the user will be prompted to choose between approximate and precise location.
2. If the website sets accuracyMode="approximate", the user will only be prompted for approximate location.
3. If the website has already been granted approximate location (as result of a request with accuracyMode="approximate") and now requests precise location, the user will be prompted to upgrade their choice from approximate to precise location.

Acquire a position

In Section 6.6, the acquire a position algorithm says "try to acquire position data from the underlying system, optionally taking into consideration the value of options.enableHighAccuracy during acquisition". It will be updated to also consider the location accuracy mode. Additionally, the algorithm will be updated to handle acquired position estimates that do not satisfy the accuracy bound. In particular, if the implementation is not able to generate an approximate position estimate then getCurrentPosition and watchPosition must return POSITION_UNAVAILABLE when the PositionOptions parameter requires approximate location.

Threats and Mitigations

Preventing Precise Location Reconstruction

A privacy risk of approximate location is that a malicious actor could potentially infer a user's precise position by collecting and correlating multiple, distinct approximate positions over a short period of time. This explainer refers to this as a "precise location reconstruction" attack. Coarsening algorithms are expected to implement mitigations against this attack.

Alternatives considered

Reusing enableHighAccuracy

A boolean option enableHighAccuracy is already specified and its default value is false. As an alternative to approximate location as an opt-in mode, provide approximate location by default and only provide precise location when it is explicitly requested.

This was rejected because changing the behavior would degrade location quality for existing applications. enableHighAccuracy is specified as a hint that may be ignored by the implementation. Historically, the high accuracy hint indicates the implementation should prefer accuracy over speed; specifically, if the system has GPS capabilities it should wait for a GPS fix instead of returning a less precise result. This tradeoff is not necessary on modern systems as system location providers are able to generate a precise estimate quickly without waiting for GPS. As a result, the behavior on most systems is not affected by the enableHighAccuracy option and many applications use the default value regardless of whether precise location is needed.

We could consider treating enableHighAccuracy=true the same as accuracyMode="precise". However, that would have a small backwards compatibility issue with navigator.permissions.query({ name: "geolocation" }), since it could result in different prompting behaviours (while querying the permission state would only return one state).

A separate powerful feature

An earlier version of this explainer proposed to gate approximate location behind a new powerful feature "geolocation-approximate", which would have been added on top of the already existent powerful feature "geolocation". This has been abandoned in response to feedback from other vendors.