Geolocation API

Instances of Geolocation are created with the internal slots in the following table:

The getCurrentPosition(successCallback, errorCallback, options) method steps are:

1. If the current settings object's relevant global object's associated Document is not fully active:
   1. Call back with error errorCallback and POSITION_UNAVAILABLE.
   2. Terminate this algorithm.
2. In parallel, request a position passing successCallback, errorCallback, and options.

The watchPosition(successCallback, errorCallback, options) method steps are:

1. If the current settings object's relevant global object's associated Document is not fully active:
   1. Call back with error passing errorCallback and POSITION_UNAVAILABLE.
   2. Return 0.
2. Let watchId be an implementation-defined unsigned long that is greater than zero.
3. Append watchId to this's [[watchIDs]].
4. In parallel, request a position passing successCallback, errorCallback, options, and watchId.
5. Return watchId.

When clearWatch() is invoked, the user agent MUST:

1. Remove watchId from this's [[watchIDs]].

To request a position, pass a PositionCallback successCallback, a PositionErrorCallback? errorCallback, PositionOptions options, and an optional watchId:

1. Let watchIDs be this's [[watchIDs]].
2. Let document be the current settings object's relevant global object's associated Document.
3. If document is not allowed to use the "geolocation" feature:
   1. If watchId was passed, remove watchId from watchIDs.
   2. Call back with error passing errorCallback and PERMISSION_DENIED.
   3. Terminate this algorithm.
4. If document's visibility state is "hidden", wait for the following page visibility change steps to run:
   1. Assert: document's visibility state is "visible".
   2. Continue to the next steps below.
5. Let descriptor be a new PermissionDescriptor whose name is "geolocation".
6. Set permission to request permission to use descriptor.
7. If permission is "denied", then:
   1. If watchId was passed, remove watchId from watchIDs.
   2. Call back with error passing errorCallback and PERMISSION_DENIED.
   3. Terminate this algorithm.
8. Wait to acquire a position passing successCallback, errorCallback, options, and watchId.
9. If watchId was not passed, terminate this algorithm.
10. While watchIDs contains watchId:
    1. Wait for a significant change of geographic position. What constitutes a significant change of geographic position is left to the implementation. User agents MAY impose a rate limit on how frequently position changes are reported.
    2. If document is not fully active or visibility state is not "visible", go back to the previous step and again wait for a significant change of geographic position.
       Note: Position updates are exclusively for fully-active visible documents
    3. Wait to acquire a position passing successCallback, errorCallback, options, and watchId.

To acquire a position, passing PositionCallback successCallback, a PositionErrorCallback? errorCallback, PositionOptions options, and an optional watchId.

1. If watchId was passed and this's [[watchIDs]] does not contain watchId, terminate this algorithm.
2. Let acquisitionTime be a new EpochTimeStamp that represents now.
3. Let timeoutTime be the sum of acquisitionTime and options.timeout.
4. Let cachedPosition be this's [[cachedPosition]].
5. Create an implementation-specific timeout task that elapses at timeoutTime, during which it tries to acquire the device's position by running the following steps:
   1. Let permission be get the current permission state of "geolocation".
   2. If permission is "denied":
      1. Stop timeout.
      2. Do the user or system denied permission failure case step.
   3. If permission is "granted":
      1. Let position be null.
      2. If cachedPosition is not null, and options.maximumAge is greater than 0:
         1. Let cacheTime be acquisitionTime minus the value of the options.maximumAge member.
         2. If cachedPosition's timestamp's value is greater than cacheTime, and cachedPosition.[[isHighAccuracy]] equals options.enableHighAccuracy, set position to cachedPosition.
      3. Otherwise, if position is not cachedPosition, try to acquire position data from the underlying system, optionally taking into consideration the value of options.enableHighAccuracy during acquisition.
      4. If the timeout elapses during acquisition, or acquiring the device's position results in failure:
         1. Stop the timeout.
         2. Go to dealing with failures.
         3. Terminate this algorithm.
      5. If acquiring the position data from the system succeeds:
         1. Set position be a new GeolocationPosition passing acquisitionTime and options.enableHighAccuracy.
         2. Set this's [[cachedPosition]] to position.
      6. Stop the timeout.
      7. Queue a task on the geolocation task source with a step that invokes successCallback with position.

   Dealing with failures:

   • If acquiring a position fails, do one of the following based on the condition that matches the failure:

     User or system denied permission:

     Call back with error passing errorCallback and PERMISSION_DENIED.

     Note: Browser permission VS OS permission

     Timeout elapsed:

     Call back with error with errorCallback and TIMEOUT.

     Data acquisition error or any other reason:

     Call back with error passing errorCallback and POSITION_UNAVAILABLE.

When instructed to call back with error, given an PositionErrorCallback? callback and an unsigned short code:

1. If callback is null, return.
2. Let error be a newly created GeolocationPositionError instance whose code attribute is initialized to code.
3. Queue a task on the geolocation task source with a step that invokes callback with error.

The enableHighAccuracy member provides a hint that the application would like to receive the most accurate location data. 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 MAY avoid using geolocation providers that consume a significant amount of power (e.g., GPS).

The timeout member denotes the maximum length of time, expressed in milliseconds, before acquiring a position expires.

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.

The coords attribute contains geographic coordinates.

The timestamp attribute represents the time when the geographic position of the device was acquired.

Instances of GeolocationPositionError are created with the internal slots in the following table:

The following task source is defined by this specifications.

The geolocation task source

Used by this specification to queue up non-blocking PositionCallback and PositionErrorCallback when performing position requests.

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 (e.g., 65 meters).

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 (e.g., 10 meters).

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.

The speed attribute denotes the magnitude of the horizontal component of the hosting device's current velocity in meters per second.

A new GeolocationPosition is constructed with EpochTimeStamp timestamp and boolean isHighAccuracy by performing the following steps:

1. Let coords be a newly created GeolocationCoordinates instance:
   1. Initialize coord's latitude attribute to a geographic coordinate in decimal degrees.
   2. Initialize coord's longitude attribute to a geographic coordinate in decimal degrees.
   3. Initialize coord's 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.
   4. Initialize coord's altitude attribute in meters above the [WGS84] ellipsoid, or null if the implementation cannot provide altitude information.
   5. Initialize coord's 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.
   6. Initialize coord's speed attribute to a non-negative real number, or as null if the implementation cannot provide speed information.
   7. Initialize coord's heading attribute in degrees, or null if the implementation cannot provide heading information. If the hosting device is stationary (i.e., the value of the speed attribute is 0), then initialize the heading to NaN.
2. Return a newly created GeolocationPosition instance with its coords attribute initialized to coords and timestamp attribute initialized to timestamp, and its [[isHighAccuracy]] internal slot set to isHighAccuracy.

PERMISSION_DENIED (numeric value 1)

Request a position failed because the user denied permission to use the API.

POSITION_UNAVAILABLE (numeric value 2)

Acquire a position failed.

TIMEOUT (numeric value 3)

The length of time specified by the timeout member has elapsed before the user agent could successfully acquire a position.

The code attribute returns the value it was initialized to (see 10.1 Constants for possible values).

The message attribute is a developer-friendly textual description of the code attribute.