Geolocation

The geolocation attribute provides the entry point for accessing the 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: If this'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. Request a position passing this, 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: If this'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. Request a position passing this, 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 Geolocation geolocation, a PositionCallback successCallback, a PositionErrorCallback? errorCallback, a PositionOptions options, and an optional watchId:

1. Let watchIDs be geolocation's [[watchIDs]].
2. Let document be the geolocation'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 geolocation's environment settings object is a non-secure context:
   1. If watchId was passed, remove watchId from watchIDs.
   2. Call back with error passing errorCallback and PERMISSION_DENIED.
   3. Terminate this algorithm.
5. 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.
6. Let descriptor be a new PermissionDescriptor whose name is "geolocation".
7. In parallel:
   1. Set permission to request permission to use descriptor.
   2. 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.
   3. Wait to acquire a position passing successCallback, errorCallback, options, and watchId.
   4. If watchId was not passed, terminate this algorithm.
   5. 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. User agents MUST consider invoking set emulated position data as a significant change.
      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. Check if an emulated position should be used by running the following steps:
         1. Let emulatedPositionData be get emulated position data passing this.
         2. If emulatedPositionData is not null:
            1. If emulatedPositionData is a GeolocationPositionError:
               1. Call back with error passing errorCallback and emulatedPositionData.code.
               2. Terminate this algorithm.
            2. Let position be a new GeolocationPosition passing emulatedPositionData, acquisitionTime and options.enableHighAccuracy.
            3. Queue a task on the geolocation task source with a step that invokes successCallback with « position » and "report".
            4. Terminate this algorithm.
      2. Let position be null.
      3. 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. :
            1. Queue a task on the geolocation task source with a step that invokes successCallback with « cachedPosition » and "report".
            2. Terminate this algorithm.
      4. 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.
      5. 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.
      6. If acquiring the position data from the system succeeds:
         1. Let positionData be a map with the following name/value pairs based on the acquired position data:

            "accuracy"

            A non-negative double that represents the accuracy value indicating the 95% confidence level in meters. Accuracy measures how close the measured coordinates are to the true position.

            "altitude"

            A double? that represents the altitude in meters above the [WGS84] ellipsoid, or null if not available. Altitude measures the height above sea level.

            "altitudeAccuracy"

            A non-negative double? that represents the altitude accuracy, or null if not available, indicating the 95% confidence level in meters. Altitude accuracy measures how close the measured altitude is to the true altitude.

            "heading"

            A double? that represents the heading in degrees, or null if not available or the device is stationary. Heading measures the direction in which the device is moving relative to true north.

            "latitude"

            A double that represents the latitude coordinates on the Earth's surface in degrees, using the [WGS84] coordinate system. Latitude measures how far north or south a point is from the Equator.

            "longitude"

            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.

            "speed"

            A non-negative double? that represents the speed in meters per second, or null if not available. Speed measures how fast the device is moving.

         2. Set position to a new GeolocationPosition passing positionData, acquisitionTime and options.enableHighAccuracy.
         3. Set this's [[cachedPosition]] to position.
         1. Set position to a new GeolocationPosition passing acquisitionTime and options.enableHighAccuracy.
         2. Set this's [[cachedPosition]] to position.
      7. Stop the timeout.
      8. Queue a task on the geolocation task source with a step that invokes successCallback with « position » and "report".

   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 » and "report".

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.

The toJSON() method returns a JSON representation of the GeolocationPosition object.

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

The following task source is defined by this specification.

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 latitude and longitude attributes denote the position, specified as a real number of degrees, in the [WGS84] coordinate system.

The accuracy attribute denotes the accuracy level of the latitude and longitude coordinates in meters (e.g., 65 meters). The accuracy attribute denotes the position accuracy radius in 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.

The toJSON() method returns a JSON representation of the GeolocationCoordinates object.

PERMISSION_DENIED (numeric value 1)

Request a position failed because the user denied permission to use the API or the request was made from an non-secure context.

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.