- If an end user [=check permission|grants permission=], + This specification provides two ways for users to share their location: +
++ An approximate location information source is a location information + source that returns positions that have been intentionally obfuscated + to make it more difficult to recover the true location. +
++ If an end user [=request permission to use|grants permission=], Geolocation:
- Request the user's current location. If the user allows it, you will - get back a position object. + A website can request a user's location, choosing either a [=precise + position=] or an [=approximate position=] via the + {{PositionOptions/accuracyMode}} member. During the permission + request process, the end-user determines the actual level of accuracy + to grant, which the [=user agent=] then uses to provide the + geographic position accordingly.
+By default, the API always attempts to return a cached position so - long as it has a previously acquired position. In this example, we - accept a position whose age is no greater than 10 minutes. If the - user agent does not have a fresh enough cached position object, it - automatically acquires a new position. + long as it has a previously acquired position that matches the + requested {{PositionOptions/accuracyMode}}. In this example, we + request a cached position whose age is no greater than 10 minutes. If + the user agent does not have a fresh enough cached position object of + the correct accuracy, it automatically acquires a new position.
-+ The {{PositionOptions/accuracyMode}} option enhances user privacy by + providing websites with the choice to request an [=approximate + position=]. This allows applications to function without needing the + user's [=precise position=], thus offering a more privacy-preserving + alternative. When an application requests an [=approximate position=], + a supporting [=user agent=], or underlying platform, attempts to + provides a less precise location. Even when a [=precise position=] is + requested, the user agent MAY provide an [=approximate position=] + instead (as defined in the [=acquire a position=] algorithm), for + example, if the user has only granted permission for approximate + accuracy. +
+- Geolocation is a [=powerful feature=] that requires - [=express permission=] from an end-user before any location data is - shared with a web application. This requirement is normatively - enforced by the [=check permission=] steps on which the - {{Geolocation/getCurrentPosition()}} and - {{Geolocation/watchPosition()}} methods rely. + Geolocation uses the [=permission=] + "geolocation-approximate" and "geolocation", which + require [=express permission=] from an end-user before any location + data is shared with a web application. This requirement is + normatively enforced by the [=request permission to use=] algorithm + on which the {{Geolocation/getCurrentPosition()}} and + {{Geolocation/watchPosition()}} methods rely. [=User agents=] with + support for [=approximate position=] MUST provide users with the + option to grant access to either a [=precise position=] or an + [=approximate position=]. This choice gives users more control over + their privacy, allowing them to share an [=approximate position=].
An end-user will generally give [=express permission=] through a user @@ -372,7 +450,7 @@
+ In line with this principle, recipients are strongly encouraged to + request the lowest level of location accuracy that is sufficient for + their application's functionality. For instance, if an application + only needs to know the user's city, it can respect user privacy by + requesting an [=approximate position=] by setting the + {{PositionOptions/accuracyMode}} option to + {{AccuracyMode/"approximate"}}. This practice of data minimization is + a key aspect of respecting user privacy. +
The recipients of location information need to refrain from retransmitting the location information without the user’s express @@ -437,27 +525,117 @@
- Geolocation is a [=default powerful feature=] identified
- by the [=powerful feature/name=] "geolocation".
+ Geolocation defines two [=permissions=] identified by
+ the names "geolocation" (for precise
+ location) and "geolocation-approximate"
+ (for approximate location). Both "geolocation" and
+ "geolocation-approximate" are [=default powerful features=].
+
+ There is a strict dependency between the [=permission states=] of + "geolocation" and "geolocation-approximate", resulting + in the following combinations of [=permission states=]: +
+| + "geolocation" + | ++ "geolocation-approximate" + | +
|---|---|
| + [=permission/"granted"=] + | ++ [=permission/"granted"=] + | +
| + [=permission/"prompt"=] + | ++ [=permission/"prompt"=] + | +
| + [=permission/"denied"=] + | ++ [=permission/"denied"=] + | +
| + [=permission/"prompt"=] + | ++ [=permission/"granted"=] + | +
| + [=permission/"denied"=] + | ++ [=permission/"granted"=] + | +
| + [=permission/"denied"=] + | ++ [=permission/"prompt"=] + | +
+ When [=query a permission|querying a permission=] via the + [[[Permissions]]] API, a user agent MAY mask the returned states of + "geolocation" and "geolocation-approximate" in order to + hide the user choice from websites.
- When checking permission - to use the API, a user agent MAY suggest time-based [=permission=] - [=permission/lifetimes=], such as "24 hours", "1 week", or choose to - remember the permission [=permission/grant=] indefinitely. However, - it is RECOMMENDED that a user agent prioritize restricting the - [=permission=] [=permission/lifetime=] to a single session: This can - be, for example, until the [=environment settings object/realm=] is + When checking permission to use the API, a user agent MAY + suggest time-based [=permission=] [=permission/lifetimes=], such as + "24 hours", "1 week", or choose to remember the permission + [=permission/grant=] indefinitely. However, it is RECOMMENDED that a + user agent prioritize restricting the [=permission=] + [=permission/lifetime=] to a single session: This can be, for + example, until the [=environment settings object/realm=] is destroyed, the end-user [=navigates=] away from the [=origin=], or the relevant browser tab is closed.
+ A recipient could potentially infer a user's [=precise position=] by + collecting and correlating multiple, distinct [=approximate + positions=]. To mitigate this risk of a refinement attack, when a + site receives an [=approximate position=], any subsequent calls from + that same site within a user-agent-defined time window SHOULD return + the exact same, cached [=approximate position=] data. A user agent + might, for example, use a time window of 15 minutes. +
+- [=Call back with error=] passing |errorCallback| and - {{GeolocationPositionError/PERMISSION_DENIED}}. -
- + A {{double}} that represents the longitude coordinates + on the Earth's surface in degrees, using the [[WGS84]] + coordinate system. Longitude measures how far east or + west a point is from the Prime Meridian.+ [=Call back with error=] passing |errorCallback| and + {{GeolocationPositionError/PERMISSION_DENIED}}. +
+ +
+ enum AccuracyMode {
+ "precise",
+ "approximate"
+ };
+
dictionary PositionOptions {
+ AccuracyMode accuracyMode = "precise";
boolean enableHighAccuracy = false;
[Clamp] unsigned long timeout = 0xFFFFFFFF;
[Clamp] unsigned long maximumAge = 0;
};
+ + The accuracyMode member is used to request a specific + level of accuracy. +
+ +The time spent waiting for the document to become visible and for - [=check permission|obtaining permission to use the API=] is not - included in the period covered by the {{PositionOptions/timeout}} + [=request permission to use|obtaining permission to use the API=] is + not included in the period covered by the {{PositionOptions/timeout}} member. The {{PositionOptions/timeout}} member only applies when [=acquiring a position=] begins.