The Geolocation API defines a high-level interface to location information associated only with the device hosting the - implementation, such as latitude and longitude. The API itself is - agnostic of the underlying location information sources. Common sources - of location information include Global Positioning System (GPS) and + implementation, such as latitude and longitude. Common sources of + location information include Global Positioning System (GPS) and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs, as well as user - input. No guarantee is given that the API returns the device's actual - location. + input. The API itself is agnostic of the underlying location + information sources, and no guarantee is given that the API returns the + device's actual location.
Since publication of the Second Edition in 2016, this specification has undergone the following changes:
- Further to the requirements listed in the previous section, - implementers of the Geolocation API are also advised to consider the - following aspects that can negatively affect the privacy of their - users: in certain cases, users can inadvertently grant permission to - the user agent to disclose their location to websites. In other - cases, the content hosted at a certain URL changes in such a way that - the previously granted location permissions no longer apply as far as - the user is concerned. Or the users might simply change their minds. + Implementers are advised to consider the following aspects that can + negatively affect the privacy of their users: in certain cases, users + can inadvertently grant permission to the user agent to disclose + their location to websites. In other cases, the content hosted at a + certain URL changes in such a way that the previously granted + location permissions no longer apply as far as the user is concerned. + Or the users might simply change their minds.
Predicting or preventing these situations is inherently difficult. @@ -453,538 +456,554 @@
- partial interface Navigator {
- [SameObject] readonly attribute Geolocation geolocation;
- };
-
- - The geolocation attribute gives access to location - information associated with the hosting device. -
-- The Geolocation interface is used by scripts to - programmatically determine the location information associated with - the hosting device. The location information is acquired by applying - a user-agent specific algorithm, creating a {{GeolocationPosition}} - object, and populating that object with appropriate data accordingly. -
-
+
+ partial interface Navigator {
+ [SameObject] readonly attribute Geolocation geolocation;
+ };
+
+
[Exposed=Window]
interface Geolocation {
- undefined getCurrentPosition(PositionCallback successCallback,
- optional PositionErrorCallback? errorCallback = null,
- optional PositionOptions options = {});
+ undefined getCurrentPosition (
+ PositionCallback successCallback,
+ optional PositionErrorCallback? errorCallback = null,
+ optional PositionOptions options = {}
+ );
- long watchPosition(PositionCallback successCallback,
- optional PositionErrorCallback? errorCallback = null,
- optional PositionOptions options = {});
+ long watchPosition (
+ PositionCallback successCallback,
+ optional PositionErrorCallback? errorCallback = null,
+ optional PositionOptions options = {}
+ );
- undefined clearWatch(long watchId);
+ undefined clearWatch (long watchId);
};
- callback PositionCallback = undefined (GeolocationPosition position);
+ callback PositionCallback = undefined (
+ GeolocationPosition position
+ );
- callback PositionErrorCallback = undefined (GeolocationPositionError positionError);
-
- - When {{Geolocation/getCurrentPosition()}} is invoked, the user - agent MUST: -
-- When watchPosition() is invoked, the user agent MUST: -
-- Otherwise, start the watch operation. This operation MUST first - attempt to obtain the current location of the device. If the - attempt is successful, the |successCallback| MUST be invoked - with a new {{GeolocationPosition}} object, reflecting the - current location of the device. If the attempt fails, [=call - back with error=], |errorCallback| and a {{unsigned short}} - code that reflects the reason for the failure. The watch - process then MUST continue to monitor the position of the - device and invoke the appropriate callback every time this - position changes. The watch process MUST continue until - the {{Geolocation/clearWatch()}} method is called with the - corresponding identifier. -
-- The implementation of the watch process MUST execute the - following set of steps: -
-- If the new position differs significantly from the previous - position in the watch process, the |successCallback| is - only invoked when a new position is obtained and this position - differs significantly from the previously reported position. The - definition of what constitutes a significant difference is left to - the implementation. Furthermore, in steps 4.2.2 and 4.3, - implementations MAY impose a rate - limit on the frequency of callbacks so as to avoid - inadvertently consuming a disproportionate amount of resources. -
-- The time that is spent obtaining the user permission MUST NOT be - included in the period covered by the {{PositionOptions/timeout}} - attribute of the {{PositionOptions}} parameter. The - {{PositionOptions/timeout}} attribute MUST only apply to the - location acquisition operation. -
-- The clearWatch() method takes one argument. When called, - it MUST first check the value of the given watchId - argument. If this value does not correspond to any previously - started watch process, then the method MUST return - immediately without taking any further action. Otherwise, the - watch process identified by the `watchId` argument MUST be - immediately stopped and no further callbacks MUST be invoked. -
-- When instructed to call back with error, given an - {{PositionErrorCallback}}? |callback:PositionErrorCallback?| and - {{unsigned short}} |code:unsigned short|: -
-- The PositionCallBack callback is invoked when a - {{GeolocationPosition}} object is available, resulting from a - cached object or the acquisition operation. The - PositionCallBack callback gets set using the - successCallback parameter. -
-- The PositionErrorCallBack callback is invoked when a - {{GeolocationPosition}} object is not available, resulting from a - timeout, a permission denied, or an unability to determine the - position of the device. The PositionErrorCallBack callback - gets set using the errorCallback parameter. -
-+ Instances of {{Geolocation}} are created with the internal slots in + the following table: +
+| + Internal Slot + | ++ Description + | +
|---|---|
| + [[\cache]] + | ++ Initialized as an [=ordered map=], with {{DOMTimeStamp}} as keys + and {{GeolocationPosition}} instances as values. Expiration of + cached key/value pairs is left as an implementation detail. + | +
| + [[\watchTasks]] + | ++ Initialized as an [=set=], with {{unsigned long}} for the keys + representing the id of a timed task. + | +
+ When {{Geolocation/getCurrentPosition()}} is invoked, the user agent + MUST: +
++ When watchPosition() is invoked, the user agent MUST: +
++ When clearWatch() is invoked, the user agent MUST: +
++ Request position by passing a {{PositionCallback}} + |successCallback:PositionCallback|, a {{PositionErrorCallback}} + |errorCallback:PositionErrorCallback|`?`, {{PositionOptions}} + |options:PositionOptions|, a {{boolean}} |repeats:boolean|, and + optionally (and only if |repeats| is true) a |previous id:long|. +
+- The {{Geolocation/getCurrentPosition()}} and - {{Geolocation/watchPosition()}} methods accept {{PositionOptions}} - objects as their third argument. + When instructed to do security and permissions checks, + given an {{PositionErrorCallback}}`?` + |errorCallback:PositionErrorCallback|:
+- In ECMAScript, {{PositionOptions}} objects are represented using - regular native objects with optional properties named - {{PositionOptions/enableHighAccuracy}}, {{PositionOptions/timeout}} - and {{PositionOptions/maximumAge}}. + When instructed to call back with error, given an + {{PositionErrorCallback}}`?` |callback:PositionErrorCallback| and an + {{unsigned short}} |code:unsigned short|:
-++
+- If |callback| is null, return. +
+- Let |error| be a a newly created {{GeolocationPositionError}} + instance whose {{GeolocationPositionError/code}} attribute is + initialized to |code|. +
+- [=Invoke=] |callback| with |error|. +
+
dictionary PositionOptions {
boolean enableHighAccuracy = false;
[Clamp] unsigned long timeout = 0xFFFFFFFF;
[Clamp] unsigned long maximumAge = 0;
};
- - The enableHighAccuracy attribute provides a hint that - the application would like to receive the best possible results. - This MAY result in slower response times or increased power - consumption. The user might also deny this capability, or the - device might not be able to provide more accurate results than if - the flag wasn't specified. The intended purpose of this attribute - is to allow applications to inform the implementation that they do - not require high accuracy geolocation fixes and, therefore, the - implementation can avoid using geolocation providers that consume a - significant amount of power (e.g. GPS). This is especially useful - for applications running on battery-powered devices, such as mobile - phones. -
-- The timeout attribute denotes the maximum length of time - (expressed in milliseconds) that is allowed to pass from the call - to {{Geolocation/getCurrentPosition()}} or - {{Geolocation/watchPosition()}} until the corresponding - |successCallback| is invoked. If the implementation is unable to - successfully acquire a new {{GeolocationPosition}} before the given - timeout elapses, and no other errors have occurred in this - interval, then the corresponding |errorCallback| MUST be invoked - with a {{GeolocationPositionError}} object whose code attribute is - set to {{GeolocationPositionError/TIMEOUT}}. Note that the time - that is spent obtaining the user permission is not included in the - period covered by the {{PositionOptions/timeout}} attribute. The - {{PositionOptions/timeout}} attribute only applies to the location - acquisition operation. -
-- In case of a {{Geolocation/getCurrentPosition()}} call, the - |errorCallback| would be invoked at most once. -
-- In case of a {{Geolocation/watchPosition()}}, the |errorCallback| - could be invoked repeatedly: the first timeout is relative to the - moment {{Geolocation/watchPosition()}} was called or the moment the - user's permission was obtained, if that was necessary. Subsequent - timeouts are relative to the moment when the implementation - determines that the position of the hosting device has changed and - a new {{GeolocationPosition}} object MUST be acquired. -
-- The maximumAge attribute indicates that the application - is willing to accept a cached position whose age is no greater than - the specified time in milliseconds. If - {{PositionOptions/maximumAge}} is set to 0, the implementation MUST - immediately attempt to acquire a new position object. Setting the - {{PositionOptions/maximumAge}} to `Infinity` MUST determine the - implementation to return a cached position regardless of its age. - If an implementation does not have a cached position available - whose age is no greater than the specified - {{PositionOptions/maximumAge}}, then it MUST acquire a new - {{GeolocationPosition}} object. In case of a - {{Geolocation/watchPosition()}}, the {{PositionOptions/maximumAge}} - refers to the first {{GeolocationPosition}} object returned by the - implementation. -
-+ The enableHighAccuracy member provides a hint that the + application would like to receive the best possible results. This MAY + result in slower response times or increased power consumption. The + user might also disable this capability, or the device might not be + able to provide more accurate results than if the flag wasn't + specified. The intended purpose of this member is to allow + applications to inform the implementation that they do not require + high accuracy geolocation fixes and, therefore, the implementation + can avoid using geolocation providers that consume a significant + amount of power (e.g. GPS). This is especially useful for + applications running on battery-powered devices. +
- [Exposed=Window, SecureContext]
- interface GeolocationPosition {
- readonly attribute GeolocationCoordinates coords;
- readonly attribute DOMTimeStamp timestamp;
- };
-
+ + The timeout member denotes the maximum length of time, + expressed in milliseconds, before acquiring a position expires. Note + that the time spent waiting for the document to become visible and + for [=Do security and permissions checks|obtaining the user + permission=] is not included in the period covered by the + {{PositionOptions/timeout}} member. The {{PositionOptions/timeout}} + member only applies to the location acquisition operation. +
++ The maximumAge member indicates that the web application + is willing to accept a cached position whose age is no greater than + the specified time in milliseconds. +
+
+ [Exposed=Window, SecureContext]
+ interface GeolocationPosition {
+ readonly attribute GeolocationCoordinates coords;
+ readonly attribute DOMTimeStamp timestamp;
+ };
+
+ - The GeolocationPosition interface is the container for the - geolocation information returned by this API. This version of the - specification allows one attribute of type {{GeolocationCoordinates}} - and a {{GeolocationPosition/timestamp}}. Future versions of the API - MAY allow additional attributes that provide other information about - this position (e.g. street addresses). + The coords attribute contains a set of geographic + coordinates.
-- The coords attribute contains a set of geographic - coordinates together with their associated accuracy, as well as a - set of other optional attributes such as altitude and speed. -
-- The timestamp attribute represents the time when the - {{GeolocationPosition}} object was acquired and is represented as a - {{DOMTimeStamp}}. -
-++ ++ `timestamp` attribute +
++ The timestamp attribute represents the time when the + geographic position of the device was acquired. +
+
[Exposed=Window, SecureContext]
interface GeolocationCoordinates {
+ readonly attribute double accuracy;
readonly attribute double latitude;
readonly attribute double longitude;
readonly attribute double? altitude;
- readonly attribute double accuracy;
readonly attribute double? altitudeAccuracy;
readonly attribute double? heading;
readonly attribute double? speed;
};
+ + The geographic coordinate reference system used by the attributes in + this interface is the World Geodetic System (2d) [[WGS84]]. No other + reference system is supported. +
+- The geographic coordinate reference system used by the attributes in - this interface is the World Geodetic System (2d) [[WGS84]]. No other - reference system is supported. + The latitude and longitude attributes are + geographic coordinates specified in decimal degrees. +
++ The accuracy attribute denotes the accuracy level of the + latitude and longitude coordinates in meters.
-- The latitude and longitude attributes are - geographic coordinates specified in decimal degrees. -
-- The altitude attribute denotes the height of the - position, specified in meters above the [[WGS84]] ellipsoid. If the - implementation cannot provide altitude information, the value of - this attribute MUST be null. -
-- The accuracy attribute denotes the accuracy level of the - latitude and longitude coordinates. It is specified in meters and - MUST be supported by all implementations. The value of the accuracy - attribute MUST be a non-negative real number. -
-- The altitudeAccuracy attribute is specified in meters. - If the implementation cannot provide altitude information, the - value of this attribute MUST be null. Otherwise, the value of the - altitudeAccuracy attribute MUST be a non-negative real number. -
-- The {{GeolocationCoordinates/accuracy}} and - {{GeolocationCoordinates/altitudeAccuracy}} values returned by an - implementation SHOULD correspond to a 95% confidence level. -
-- The heading attribute denotes the direction of travel of - the hosting device and is specified in degrees, where 0° ≤ heading - < 360°, counting clockwise relative to the true north. If the - implementation cannot provide heading information, the value of - this attribute MUST be null. If the hosting device is stationary - (i.e. the value of the {{GeolocationCoordinates/speed}} attribute - is 0), then the value of the heading attribute MUST be NaN. -
-- The speed attribute denotes the magnitude of the - horizontal component of the hosting device's current velocity and - is specified in meters per second. If the implementation cannot - provide speed information, the value of this attribute MUST be - null. Otherwise, the value of the speed attribute MUST be a - non-negative real number. -
-++ ++ `altitude` and `altitudeAccuracy` attributes +
++ The altitude attribute denotes the height of the position, + specified in meters above the [[WGS84]] ellipsoid. +
++ The altitudeAccuracy attribute represents the altitude + accuracy in meters. +
++ ++ `heading` attribute +
++ The heading attribute denotes the direction of travel of + the hosting device and is specified in degrees, where 0° ≤ heading + < 360°, counting clockwise relative to the true north. +
++ ++ `speed` attribute +
++ The speed attribute denotes the magnitude of the + horizontal component of the hosting device's current velocity in + meters per second. +
++ ++ Constructing a `GeolocationPosition` +
++ A new `GeolocationPosition` is constructed with {{unsigned + long}} |timestamp:unsigned long| by performing the following steps: +
++
+- Let |coords| be a newly created {{GeolocationCoordinates}} + instance: +
++
+- Initialize |coord|'s {{GeolocationCoordinates/latitude}} + attribute to a geographic coordinate in decimal degrees. +
+- Initialize |coord|'s {{GeolocationCoordinates/longitude}} + attribute to a geographic coordinate in decimal degrees. +
+- Initialize |coord|'s {{GeolocationCoordinates/accuracy}} + attribute to a non-negative real number. The value SHOULD + correspond to a 95% confidence level with respect to the + longitude and latitude values. +
+- Initialize |coord|'s {{GeolocationCoordinates/altitude}} + attribute in meters above the [[WGS84]] ellipsoid, or `null` if + the implementation cannot provide altitude information. +
+- Initialize |coord|'s + {{GeolocationCoordinates/altitudeAccuracy}} attribute as + non-negative real number, or to `null` if the implementation + cannot provide altitude information. If the altitude accuracy + information is provided, it SHOULD correspond to a 95% confidence + level. +
+- Initialize |coord|'s {{GeolocationCoordinates/speed}} + attribute to a non-negative real number, or as `null` if the + implementation cannot provide speed information. +
+- Initialize |coord|'s {{GeolocationCoordinates/heading}} + attribute in degrees, or `null` implementation cannot provide + heading information. If the hosting device is stationary (i.e. + the value of the {{GeolocationCoordinates/speed}} attribute is + 0), then initialize the {{GeolocationCoordinates/heading}} to + `NaN`. +
+- Return a newly created {{GeolocationPosition}} instance with its + {{GeolocationPosition/coords}} attribute initialized to |coords| and + {{GeolocationPosition/timestamp}} attribute initialized to + |timestamp|. +
+
[Exposed=Window]
interface GeolocationPositionError {
const unsigned short PERMISSION_DENIED = 1;
@@ -994,55 +1013,61 @@
readonly attribute DOMString message;
};
- - The code attribute MUST return the appropriate code from - the following list: -
-- The message attribute is a developer-friendly textual - description of the {{GeolocationPositionError/code}} attribute. -
-- The purpose of the {{GeolocationPositionError/message}} attribute - is to assist with debugging and it's not intended to be shown to - end users. -
-+ The code attribute returns the value it was initialized to + (see [[[#constants]]]). +
++ The message attribute is a developer-friendly textual + description of the {{GeolocationPositionError/code}} attribute. +
++ The purpose of the {{GeolocationPositionError/message}} attribute is + to assist with debugging - as such, they probably won't make any + sense if shown to an end user. Please use the + {{GeolocationPositionError}}'s {{GeolocationPositionError/code}} + attribute to create user-friendly localized error messages. +
- The scope of this specification does not include providing a markup - language of any kind. -
-- The scope of this specification does not include defining a new - [=url/scheme=] for building URLs that identify geographic locations. + World Geodetic System coordinates [[WGS84]]. It does not include + providing a markup language of any kind, nor does not include + defining a new [=url/scheme=] for building URLs that identify + geographic locations.
- A user finds herself in an unfamiliar city area. She wants to check - her position so she uses her hand-held device to navigate to a - Web-based mapping application that can pinpoint her exact location - on the city map using the Geolocation API. She then asks the Web - application to provide driving directions from her current position - to her desired destination. + A user finds themselves in an unfamiliar city area. They want to + check their position so they use their device to navigate to a + mapping application that can pinpoint their location on the city + map using the Geolocation API. The user then asks the Web + application to provide driving directions from their current + position to a different destination.
+ The Geolocation API needs to: +