Add support for approximate geolocation

[alvinjiooo]

Closes #182

This commit introduces the ability for users and developers to request a less precise, privacy-preserving "approximate" location.

Key changes include:

• A new accuracyMode option in PositionOptions to request either "precise" or "approximate" location.
• A new "Geolocation permissions" section, which include new "geolocation-approximate" powerful feature.
• Updated "Request a position" and "Acquire a position" algorithms to handle the new accuracy levels.
• Expanded the introduction with a non-normative description of what an "approximate location" is.
• Added a normative privacy requirement for user agents to mitigate precise location reconstruction by caching approximate locations for a period of time.

The following tasks have been completed:

• Modified Web platform tests (link to pull request)

Implementation commitment (and no objections):

• WebKit
• Chromium (https://bugs.chromium.org/p/chromium/issues/detail?id=)
• Gecko (https://bugzilla.mozilla.org/show_bug.cgi?id=)

Documentation (new feature):

• Updated implementation report
• Pinged MDN
• Added example to README or spec

For documentation, either create an issue or pull request in MDN's Content repo - providing as much information as you can. PR is prefered.

Approximate Geolocation explainer

---

Preview | Diff

[reillyeon]

For readability as you iterate on this proposal it's okay for this PR to directly change the specification text however to land this change the changes need to be enclosed in the correct candidate additions/corrections/deletions syntax.

[marcoscaceres]

@reillyeon if it's ok, let's move this to CR first (i.e., let's not waste time with the ins/dels). We are close to publishing as CR again.

[Copilot]

Pull Request Overview

This PR adds support for approximate location positioning to the Geolocation API specification. It introduces a privacy-preserving alternative to precise location sharing, allowing applications to request coarse-grained location data when high accuracy is not needed.

Key changes:

• Introduces accuracyMode option with "precise" (default) and "approximate" values
• Adds new "geolocation-approximate" permission alongside existing "geolocation" permission
• Implements separate caching for precise and approximate positions
• Updates permission request flows to allow users to choose between precise and approximate location sharing

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[antosart]

A few comments wrt the permission handling.

[marcoscaceres]

Please remove all the "Candidate addition" stuff. We don't need any of that additional markup anymore (but leave the rest of normative text there 😄 ) .

[nondebug]

lgtm

[marcoscaceres]

Ok, added to Privacy WG agenda:
w3c/privacywg#22

Will ping Mozilla folks directly.

[marcoscaceres]

Done: mozilla/standards-positions#1398

[marcoscaceres]

Oops, thanks @alvinjiooo for pinging @nondebug! Added him to the Moz position too.

[antosart]

Fyi @tomvangoethem pointed out that the paragraph regarding State 5. was confusing, so I tried to make it a bit more clear, see the diff here.

[tomvangoethem]

Thanks for the ping! (I'm Tom from the Chrome Privacy team).

My understanding of the proposed changes to make geolocation-approximate queryable is that these don't actually reveal a user's chosen option. Let me create another table to explain:

Requested accuracy mode	User decision	Internal state	query("geolocation")	query("geolocation-approximate")
approximate	granted	granted/prompt	prompt	granted
approximate	denied	denied/denied	denied	denied
precise	granted precise	granted/granted	granted	granted
precise	granted approximate	granted/denied	granted	granted
precise	denied	denied/denied	denied	denied

So the prompt/granted case for querying "geolocation"/"geolocation-approximate" would only indicate whether a user granted or denied an approximate-only permission prompt where the site selected {accuracyMode:"approximate"} (which can already be inferred anyway). And crucially, there's no observable difference through query() after the user was presented with a choice between precise and approximate.

Given that there is no net-new information added with query("geolocation-approximate"), I wonder whether I am missing something or whether there's a misunderstanding that snuck in during the discussion?

[marcoscaceres]

Hi @tomvangoethem! Welcome! 🤗

so yeah, that’s my argument: developers don’t get any additional value/info from querying “geolocation-approximate” given that what matters is .accuracy, so dropping it simplifies everything for developers, users, and implementers while being fully backwards compatible.

[antosart]

so yeah, that’s my argument: developers don’t get any additional value/info from querying “geolocation-approximate” given that what matters is .accuracy, so dropping it simplifies everything for developers, users, and implementers while being fully backwards compatible.

I wanted to chime in again since I think this is actually where we disagree. I believe that having all the following three properties:

1. backwards compatibility
2. a way for websites to use getCurrentPosition({accuarcyMode: 'approximate'}) in conjunction with permissions.query() as expected
3. the possibility for websites to trigger an upgrade flow (i.e. the possibility to use in the future getCurrentPosition({accuracyMode: 'precise'}) and ask the user for precise location even if they now just use getCurrentPositoin({accuracyMode: 'approximate'})

is what makes everything simple and usable for web developers. In particular, it is what allows them to easily switch to using approximate-only (if that fits their use case) without regressions in functionality and without precluding the possibility of using precise position in the future, which is what we want to encourage also from a privacy point of view.

I don't think it's possible to have 1. 2. and 3. without a separate queryable permission for approximate location only.

[marcoscaceres]

Mmm, will reverify tomorrow if it’s a possibility with code. I concluded above the it was absolutely possible, but maybe 🤔 I made a mistake. I’ll try to prove it again purely with JS.

[alvinjiooo]

Ok, added to Privacy WG agenda: w3c/privacywg#22

Will ping Mozilla folks directly.

cc @jyasskin

[tomvangoethem]

I just wanted to elaborate a bit more on the privacy perspective: ideally, we want to encourage sites to request approximate-only when that's all the information they need (see also the W3C privacy principles on data minimization). Being able to upgrade the geolocation permission to precise (if this would be required for another use case on the site) and having full support to do so (i.e. having a representative permissions.query()), seems like it would encourage such usage.

While it's possible to mimic the behavior in JS with a number of caveats, it's far from ideal. I would imagine that code would look something like this:

navigator.geolocation.getCurrentPosition((pos) => {
    localStorage.setItem('canAskForPrecise', true);
    processPosition(pos);
}, (err) => {
    localStorage.setItem('canAskForPrecise', false);
}, {accuracyMode: 'approximate'});

// ... later, if precise is required:

// NOTE: this only works if the user did not make any changes to the granted permissions
if (localStorage.getItem('canAskForPrecise')) {
    navigator.geolocation.getCurrentPosition(handlePrecisePos, {accuracyMode: 'precise'});
}

By having the separate query("geolocation") and query("geolocation-approximate") the above would look like:

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

// ... later, if precise is required:

// NOTE: if this returns "prompt", we are sure we can ask the user for precise location
if ((await navigator.permissions.query({name: 'geolocation'})).state == 'prompt') {
  navigator.geolocation.getCurrentPosition(handlePrecisePos, {accuracyMode: 'precise'});
}

The latter looks way more intuitive to me, provides clarity to sites, and better supports the (from a privacy perspective) preferred approach of asking for approximate location when that is all the information that is (initially) needed.

[marcoscaceres]

@antosart, I built a test harness to verify whether a single-permission model can satisfy your three properties. The results are more nuanced than I expected.

Demo: https://marcoscaceres.github.io/geolocation-permissions-demo/ (source)

What it tests

The demo implements both models (Chromium's two-permission proposal and WebKit's single-permission proposal) as mock APIs, then tests developer patterns across all four permission states to see whether permissions.query() accurately predicts getCurrentPosition() behavior.

The finding

The results depend on an assumption that neither of us has articulated: what does getCurrentPosition() (no accuracyMode) do when only the "geolocation-approximate" permission has been granted?

We assume the UA returns approximate data rather than re-prompting, since the user already consented to sharing location. Under that assumption, both models behave differently when the "geolocation-approximate" permission is granted:

• Chromium's model returns "prompt" for query({name: "geolocation"}) (conservative: treats code without accuracyMode as requesting precise). However, getCurrentPosition() succeeds without prompting because the "geolocation-approximate" permission was granted. Legacy sites would show unnecessary "share location" UI.
• WebKit's model returns "granted" for query({name: "geolocation"}) (the user has granted some level of access). If the site then calls getCurrentPosition({accuracyMode: "precise"}), the browser prompts because the user is being asked to share more than they originally consented to.

The enableHighAccuracy precedent

The existing enableHighAccuracy option in PositionOptions is a hint with no separate queryable permission and no result attribute reporting what the UA did. query({name: "geolocation"}) returning "granted" has never guaranteed high-accuracy results. The developer checks coords.accuracy after the call. This is the existing precedent for how option hints interact with the permission model.

On @tomvangoethem's code comparison

Tom's example makes the two-permission model look clean for the upgrade case specifically. But in a real app, the full lifecycle with two permissions is:

// Two-permission: managing TWO states + their relationship
const approx = await permissions.query({
  name: "geolocation-approximate"
});
const precise = await permissions.query({
  name: "geolocation"
});
approx.onchange = () => { /* update UI */ };
precise.onchange = () => { /* update UI */ };

vs.

// Single-permission: ONE state
const geo = await permissions.query({name: "geolocation"});
geo.onchange = () => { /* update UI */ };

The localStorage workaround in Tom's "without" example is a strawperson. You don't need to predict whether a prompt will appear. You just call getCurrentPosition({accuracyMode: "precise"}) when the user taps "set pickup location." If it prompts, that's fine: the user initiated the action, they expect interaction. The standard getUserMedia() pattern is to call the API and handle the result, not to pre-check query({name: "camera"}).

Passive queryability

Under the two-permission model, a script can determine whether the user chose approximate-only by querying both permission names on page load, without calling getCurrentPosition() and without a user gesture. Under the single-permission model, only "geolocation" is queryable, so this distinction is not observable until the API is actually called. See w3c/permissions#52 for background on passive queryability concerns.

Additionally, under the two-permission model, a third-party script can subscribe to onchange on "geolocation-approximate", wait for the user to grant access to the embedding page, then call the API at that moment without an additional prompt. The user sees one prompt (from the legitimate page), but multiple scripts get location data.

The question for the group

Does the developer need to PREDICT prompts, or just HANDLE them? The web platform has always used the handle-the-result pattern. Adding a second queryable permission to enable prompt prediction comes at a cost: any third-party script can passively observe the user's accuracy preference without a gesture. The prediction use case is a nice-to-have; the passive queryability is a privacy concern.

I'd welcome @tomvangoethem's further thoughts on this tradeoff.

[antosart]

Thanks for trying this out concretely. One observation though:

The results depend on an assumption that neither of us has articulated: what does getCurrentPosition() (no accuracyMode) do when only the "geolocation-approximate" permission has been granted?

Actually, in our proposal this is covered in the explainer and is also explicitly specified in the current version of the spec PR (although it's arguably not that easy to decode).

In particular, there are two cases in which only "geolocation-approximate" is granted, depending on the state of "geolocation":

• If "geolocation" is "prompt" then getCurrentPosition() prompts for upgrading location access from approximate to precise. Note that this happens if the user has only been prompted for "geolocation-approximate" and not for "geolocation" in the past, which is the case if the site only used getCurrentPosition(approximate) previously.
• If "geolocation" is "denied" then getCurrentPosition() returns approximate location without prompting. (This could happen if the user has been prompted to upgrade from approximate to precise, and denied the upgrade request.)

Chromium's model returns "prompt" for query({name: "geolocation"}) (conservative: treats code without accuracyMode as requesting precise). However, getCurrentPosition() succeeds without prompting because the "geolocation-approximate" permission was granted. Legacy sites would show unnecessary "share location" UI.

So this is actually incorrect. Chromium's model respects the invariant "permissions.query() returns prompt iff getCurrentPosition() shows a prompt".

[antosart]

Inspired by your idea @marcoscaceres I created an emulator of how the permission model we are proposing would work. Playing with that is much easier than reading through the explainer. PTAL!

[alvinjiooo]

@marcoscaceres / @antosart / @tomvangoethem ,
Based on our discussion, I added the note in 3.4 Geolocation permissions for "geolocation-approximate" queryability.
PTAL and let me know if that looks good to you.
Thanks!

[antosart]

I think we should also add:

If the permission state of "geolocation" is granted and the permission state of "geolocation-approximate" is changed to prompt, set the permission state of "geolocation" to prompt.

If the permission state of "geolocation-approximate" is denied and the permission state of "geolocation" is changed to prompt, set the permission state of "geolocation-approximate" to prompt.

[alvinjiooo]

I think current algorithm give the basic coherence between two permissions seems good to me. I am not sure whether should we add more coherence here given that it might bring more questions and different agents might want to implement this differently. Maybe let's add it later from a new issue so we can discuss further on finer permission control for this feature?

[marcoscaceres]

Exactly... what @alvinjiooo said.

Maybe we can add a note or issues here saying we are still trying to figure this out. And we can link to the issue via <aside class="issue" data-number="??">

[marcoscaceres]

This should be handled by the Permissions spec, as these changes are bound to the event loop.

If anything, changes state needs to "queue at task on the ??? task source to ..." so the permission state can change at the appropriate time at the turn of the event loop (so the PermissionState can do what it needs to do).

[antosart]

The point is that the PR as currently written assumes that the combined permission states are in one of the 6 allowed states. The algorithms break otherwise. Given that, I do believe that we should explicitly listing the 6 allowed states (see comment above) and also write that implementations must make sure that everything stays consistent at all times. If we list things that implementors must do, I say either we list all of them or we skip all.

[marcoscaceres]

I’ll have another look. If they as look up tables for state, the yes: make sense to keep them. I didn’t get that sense tho, as the permission state is maintained independently by the permission store (as permissions might change at any time for any reason… they expire, users changes them, os level changes etc. and the change might not always be observable by script).

[alvinjiooo]

@marcoscaceres ,
I discussed with @antosart and decided to remove the new/old permission coherence description from this PR and added a aside tag with issue #231 to track the follow up discussion. Currently we still keep the table for the permission state combos which we believe you also think that is reasonable to have it in this PR. Please take a look at the latest version of the PR and let us know if this looks good to you.
Thanks!

[alvinjiooo]

@marcoscaceres / @antosart / @tomvangoethem , Based on our discussion, I added the note in 3.4 Geolocation permissions for "geolocation-approximate" queryability. PTAL and let me know if that looks good to you. Thanks!

Hi @marcoscaceres ,
Do you get a chance to take a look at latest PR? Especially for the note in 3.4 Geolocation permissions.
Thanks!

[marcoscaceres]

Mostly just nits now... but question around the permissions table.

Otherwise looking pretty good.

[alvinjiooo]

I updated for most comments but leave the permission states combination table since @antosart and @marcoscaceres still having discussion. For other comments I have them updated and resolved.