Add support for approximate geolocation

[alvinjiooo]

Closes #182

The following tasks have been completed:

• Modified Web platform tests (link to pull request)

Implementation commitment (and no objections):

• WebKit (https://bugs.webkit.org/show_bug.cgi?id=)
• 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.

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-approximate permission and policy, which is implicitly granted if the "geolocation" permission is given.
• Separate internal caching for precise and approximate positions.
• Updated "Request a position" and "Acquire a position" algorithms to handle the new accuracy levels, permission fallback, and caching logic.
• The GeolocationPosition interface now includes an accuracyMode attribute to reflect the accuracy of the returned position.
• 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.

Closes #182

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]

I have new permission policy part dropped. PTAL and thanks.

[marcoscaceres]

Updated the PR template at the top of the PR... we need to file bugs still, etc.

[antosart]

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 😄 ) .

Should we split out the "Candidate addition" removal stuff in a separate CL? It would make this one a little easier to parse :)

[marcoscaceres]

Yep, that’s coming in #181

We should be landing that really soon. @siusin, how long till we can republish as CR? 🙏

[siusin]

We should be landing that really soon. @siusin, how long till we can republish as CR? 🙏

Once #215 gets fixed, we will give the AC Reps one week to review the changes. We can then complete the previous REC cycle and publish a new CR.

[alvinjiooo]

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 😄 ) .

Should we split out the "Candidate addition" removal stuff in a separate CL? It would make this one a little easier to parse :)

It sounds like #181 will be landed soon once the status change happened. I will rebased this PR again once that one is landed.

[alvinjiooo]

Hi @marcoscaceres and @antosart ,
I rebased the PR and now we finally get rid of ins and del tag.
PTAL and share your comments.
Thanks!

[antosart]

(nit) I believe you can just include the s (<dfn>location information sources</dfn>) since autolinking shouldn't care about plurals. That makes the spec look nicer.

(I also think this dfn is kind of weird since it's not defining anything, but I'm not sure about that.)

[alvinjiooo]

Ack, I will remove the dfn for location information source. I think our points here is to define precise position and approximate position. I will update this in next patch.

[antosart]

I propose to change as following:

              <li>If |approximatePermissionState| is [=permission/"granted"=]
              and |permissionDesc|'s [=permission state=] is
              [=permission/"denied"=], set |status|'s to
              [=permission/"granted"=]. Otherwise, set |status|'s
              {{PermissionStatus/state}} to |permissionDesc|'s [=permission state=].
              </li>

which makes it more clear that there is only one exception to returning |permissionDesc|'s [=permission state=].

[alvinjiooo]

I actually have question for the new proposal.

For what we have right now, it only provide one exception when:
approximate: grant
precise: prompt
final permission state: prompt
Everything else determined by approximate's permission state.

But for new proposal, when:
approximate: denied
-> final permission state is determined by precise's state, which can be anything from {denied, granted, prompt}. But I think if approximate's state is defined the final state should be denied too.

Can you please clarify if I missed anything?

[antosart]

I think we are not writing anywhere that there are dependencies between the values of the permissions, right? The Permissions spec doesn't really have support for that, but it doesn't specify how permission state can be changed (e.g. in site settings) either. So I believe we can add a sentence here, explaining that "geolocation" should always be stricter than "geolocation-approximate". We can even include the full list of the allowed states. We can also explain that vendors should always ensure that the states are coherent, so when changing one of the two values for "geolocation" or "geolocation-approximate" they might have to change the value of the other one, too.

I think that's important because the algorithms below assume that we are always in one of the allowed states.

[alvinjiooo]

That sounds good, I will add a new paragraph explicitly defining the directional relationship: granting precise location implies granting approximate location, and denying approximate location implies denying precise location. I'll include the full list of valid state combinations and explicitly require implementers to maintain this coherence when values change.

        <p>
          There is a strict dependency between the [=permission state=]s of
          <code>"geolocation"</code> and <code>"geolocation-approximate"</code>.
          Specifically, granting precise location implies granting approximate
          location, and denying approximate location implies denying precise
          location. This results in the following allowed combinations of states:
        </p>
        <ul>
          <li>Both are [=permission/"granted"=].</li>
          <li>Both are [=permission/"prompt"=].</li>
          <li>Both are [=permission/"denied"=].</li>
          <li><code>"geolocation-approximate"</code> is [=permission/"granted"=] and <code>"geolocation"</code> is [=permission/"prompt"=].</li>
          <li><code>"geolocation-approximate"</code> is [=permission/"granted"=] and <code>"geolocation"</code> is [=permission/"denied"=].</li>
          <li><code>"geolocation-approximate"</code> is [=permission/"prompt"=] and <code>"geolocation"</code> is [=permission/"denied"=].</li>
        </ul>
        <p>
          Implementers MUST ensure that these states remain coherent. For
          example, if a user changes the [=permission state=] of
          <code>"geolocation-approximate"</code> to [=permission/"denied"=] via
          site settings, the user agent MUST automatically update
          <code>"geolocation"</code> to [=permission/"denied"=] as well.
          Similarly, if <code>"geolocation"</code> is changed to
          [=permission/"granted"=], <code>"geolocation-approximate"</code> MUST
          also become [=permission/"granted"=].
        </p>

Does this make sense to you?