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

[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.

[saschanaz]

Is there any reason why there should be a separate geolocation-approximate permission instead of doing { name: "geolocation", approximate: true }, like Push does?

[alvinjiooo]

Is there any reason why there should be a separate geolocation-approximate permission instead of doing { name: "geolocation", approximate: true }, like Push does?

@saschanaz, Thanks for great suggestion, through email discussion GeolocationPermissionDescriptor seems to be more acceptable option. So I went ahead to reshape this PR now adopting GeolocationPermissionDescriptor instead of dual permission mode.

Hi @marcoscaceres,
Can you please review the latest PR? Let's focus on just permission model update instead editorial things which I think the most important thing now we should align all together. If the GeolocationPermissionDescriptor permission model looks good to you then let's finalize the PR with closer look after. Thanks!

[antosart]

Note that a custom GeolocationPermissionDescriptor was included in our initial proposal. We changed that in response to feedback.

Please also see the Permissions issue w3c/permissions#459 I opened. People who chimed in so far seem to agree that permission aspects are probably a bad choice for booleans, and I personally tend to agree.

[antosart]

@alvinjiooo I think the main problem with the current version of the PR is that this is not backwards compatible. When requesting a position, you fall back to checking the approximate permission if the precise permission is not granted However, you got rid of the overridden permission query algorithm. This means that you would end up with permissions.query(precise) returning denied while getCurrentPosition(precise) returns approximate location, which seems something we don't want.

[alvinjiooo]

@alvinjiooo I think the main problem with the current version of the PR is that this is not backwards compatible. When requesting a position, you fall back to checking the approximate permission if the precise permission is not granted However, you got rid of the overridden permission query algorithm. This means that you would end up with permissions.query(precise) returning denied while getCurrentPosition(precise) returns approximate location, which seems something we don't want.

I wonder when you mention permissions.query(precise) does that mean GeolocationPermissionDescriptor = {name= "geolocation", accuracyMode = "precise"} ?
If that is the case, when user grant on approximate permission, I think this may not necessarily return denied, the user agent can decide whether to return 'promptor 'denied' based on their decision on permission model. But the expectation for this case is thatpermissions.query(approximate)` (when accuracyMode = "approximate" in GPD) it should return "granted".

[alvinjiooo]

Is there any reason why there should be a separate geolocation-approximate permission instead of doing { name: "geolocation", approximate: true }, like Push does?

@saschanaz, Thanks for great suggestion, through email discussion GeolocationPermissionDescriptor seems to be more acceptable option. So I went ahead to reshape this PR now adopting GeolocationPermissionDescriptor instead of dual permission mode.

Hi @marcoscaceres, Can you please review the latest PR? Let's focus on just permission model update instead editorial things which I think the most important thing now we should align all together. If the GeolocationPermissionDescriptor permission model looks good to you then let's finalize the PR with closer look after. Thanks!

Hi @marcoscaceres ,
Do you get a chance to review latest version of PR#195?
Thanks,
Alvin

[antosart]

@marcoscaceres I went ahead and drafted w3c/permissions#477. Would something like that be helpful to address your concerns wrt exposing the new permission?

[antosart]

@alvinjiooo I think the main problem with the current version of the PR is that this is not backwards compatible. When requesting a position, you fall back to checking the approximate permission if the precise permission is not granted However, you got rid of the overridden permission query algorithm. This means that you would end up with permissions.query(precise) returning denied while getCurrentPosition(precise) returns approximate location, which seems something we don't want.

I wonder when you mention permissions.query(precise) does that mean GeolocationPermissionDescriptor = {name= "geolocation", accuracyMode = "precise"} ? If that is the case, when user grant on approximate permission, I think this may not necessarily return denied, the user agent can decide whether to return 'promptor 'denied' based on their decision on permission model. But the expectation for this case is thatpermissions.query(approximate)` (when accuracyMode = "approximate" in GPD) it should return "granted".

Yes, in your current version, the spec mandates for permissions.query({name: "geolocation", accuracyMode: "precise"}) to return "denied" if the user granted approximate location only. Yet in that case navigator.geolocation.getCurrenPosition({accuracyMode: 'precise'} would resolve successfully with approximate location.

Regardless, I would suggest to go back to a version of this PR that reflects the explainer, since it's otherwise difficult to understand what we are trying to spec.

[alvinjiooo]

Yes, in your current version, the spec mandates for permissions.query({name: "geolocation", accuracyMode: "precise"}) to return "denied" if the user granted approximate location only. Yet in that case navigator.geolocation.getCurrenPosition({accuracyMode: 'precise'} would resolve successfully with approximate location.

Actually currently version of PR didn't define how permissions.query should behave wrt to GeolocationPermissionDescriptor, that is actually up to user agent to decide what to return when accuracyMode is "precise" in GeolocationPermissionDescriptor with "name" is "geolocation" based on their internal model. The user agent can decide whether to prompt or directly decide the state of it (based on their own permission model).

The algorithm at Request a position first check permission with accuracyMode is "precise" (where user agent can decide to prompt or directly return state when user previously grant for "approximate"). if the final result is not "grant", it then retreat and check permission state for GeolocationPermissionDescriptor with accuracyMode is "approximate". This is actually same pattern as previous version did for first checking permission with "geolocation" permission then "geolocation-approximate" permission. I hope this explain better on that the new version of PR does.

Let me know if you still feel the previous version of PR ("geolocation" + "geolocation-approximate" permission name) should be the way to moving forward. Thanks.

[antosart]

Actually currently version of PR didn't define how permissions.query should behave wrt to GeolocationPermissionDescriptor, that is actually up to user agent to decide what to return when accuracyMode is "precise" in GeolocationPermissionDescriptor with "name" is "geolocation" based on their internal model. The user agent can decide whether to prompt or directly decide the state of it (based on their own permission model).

The Permissions spec does mandate the return value of permissions.query() (it's not up to the user agent). In particular, that return value is the same as the return value of the permission query algorithm, which an earlier version of this PR was overriding, but the current version does not anymore.

[alvinjiooo]

Actually currently version of PR didn't define how permissions.query should behave wrt to GeolocationPermissionDescriptor, that is actually up to user agent to decide what to return when accuracyMode is "precise" in GeolocationPermissionDescriptor with "name" is "geolocation" based on their internal model. The user agent can decide whether to prompt or directly decide the state of it (based on their own permission model).

The Permissions spec does mandate the return value of permissions.query() (it's not up to the user agent). In particular, that return value is the same as the return value of the permission query algorithm, which an earlier version of this PR was overriding, but the current version does not anymore.

Thanks for pointing this out. Since previous PR also need custom permission query and custom algorithm because the new permission "geolocation-approximate". I would imagine GeolocationPermissionDescriptor can do similar way. But I don't think defining it will be the best thing to do here since there is already different ideas for the permission model for this feature from different browser vendors, it seems to me GeolocationPermissionDescriptor maybe more acceptable than new permission "geolocation-approximate".

I will first revert the PR back to "geolocation-approximate" for now to where we start to invite Mozilla to review, but I am not sure if it is meaningful to continue to update it before we get clear idea what is acceptable model to everyone.

[antosart]

@marcoscaceres I went ahead and drafted w3c/permissions#477. Would something like that be helpful to address your concerns wrt exposing the new permission?

Hey @marcoscaceres. I was wondering if you had time to consider the proposal of having this PR together with something like w3c/permissions#477 (which we could iterate upon and improve) to clarify that browsers can mask the queried permission state in some cases (as WebKit already does for "geolocation"). We could even change that and write that browser might just throw when querying some permissions.

[antosart]

I tried to write a version of this PR which does not define a different permission name or permission model and instead follows the proposed WebKit model.

Since the discussion on this PR has been already quite long, I created a separate PR #233.