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. Candidate Correction: Updated reference to the global object to use If this for consistency in error handling within geolocation retrieval. 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. Candidate Correction: Simplified reference to the global object in the method steps for checking document's activity status. 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 document is not allowed to use "geolocation-approximate" :
      1. If watchId was passed, remove watchId from watchIDs .
      2. Call back with error passing errorCallback and PERMISSION_DENIED .
      3. Terminate this algorithm.
   2. Otherwise: Set options . accuracyMode to " approximate ".
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-approximate" if options . accuracyMode is " approximate ", otherwise "geolocation" .
7. In parallel :
   1. Let resolvedPermissionState be null .
   2. If permissionName is : "geolocation-approximate" :
      1. Set permission resolvedPermissionState to the result of running request permission to use descriptor .
   3. Otherwise ( permissionName is "geolocation" ):
      1. Let precisePermissionStatus be request precise geolocation permission .
      2. Set resolvedPermissionState to precisePermissionStatus .state.
   4. If permission resolvedPermissionState is "denied", then: "denied":
      1. If watchId was passed, remove watchId from watchIDs .
      2. Call back with error passing errorCallback and PERMISSION_DENIED .
      3. Terminate this algorithm.
   5. Wait to acquire a position passing successCallback , errorCallback , options , and watchId .
   6. If watchId was not passed, terminate this algorithm.
   7. 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 permissionStatus be get the current result of running the precise permission query algorithm given a new PermissionDescriptor with its name set to "geolocation".
   2. Let effectiveAccuracy be null .
   3. If permissionStatus . state of is granted :
      1. If options . "geolocation" accuracyMode is "approximate":
         1. Set effectiveAccuracy to "approximate".
      2. Otherwise ( options . accuracyMode is "precise"):
         1. Set effectiveAccuracy to permissionStatus . accuracyMode .
   4. If permission effectiveAccuracy is "denied": null :
      1. Stop timeout .
      2. Do the user or system denied permission failure case step.
      3. Terminate this algorithm.
   5. If Otherwise, run belows steps to determine permission is "granted": position :
      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 . , and effectiveAccuracy .
            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. Candidate Correction: Updated to ensure that the algorithm terminates immediately if a valid cached position is used, avoiding unnecessary steps. If cachedPosition 's timestamp 's value is greater than cacheTime , and effectiveAccuracy equals cachedPosition 's accuracyMode , 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, with the following considerations:
         1. If effectiveAccuracy is "approximate", the user agent SHOULD acquire a position with a level of accuracy that is sufficient to protect user privacy (e.g., city-level accuracy). The enableHighAccuracy member is ignored.
         2. If effectiveAccuracy is "precise", the user agent SHOULD acquire a position, optionally taking into consideration the value of options . enableHighAccuracy during acquisition. .
   6. 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.
   7. If acquiring the position data from the system succeeds: Candidate Correction: We now use a map to represent the position data. Clarified the units and reference systems for latitude, longitude, and altitude, ensuring consistency with the updated attribute definitions. Updated the descriptions of the speed and heading to specify measurement units and conditions for null values, aligning with the overall enhancements to attribute accuracy and clarity.
      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 . Set this 's [[cachedPosition]] to position . Set position to a new GeolocationPosition passing acquisitionTime and options effectiveAccuracy . enableHighAccuracy .
      3. Set this 's [[cachedPosition]] to position .
   8. Stop the timeout .
   9. 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 accuracyMode member is used to request a specific level of accuracy. It can be set to "precise" to request the most accurate location data available, or "approximate" to receive a less accurate location that protects user privacy. The default value is "precise".

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() accuracyMode method attribute indicates the accuracy level of the position, which can be either "precise" or "approximate" . This reflects the level of accuracy that was granted and used to allow obtain the position.

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.

1. Let coords be a newly created GeolocationCoordinates instance.
2. For each key → value in positionData :
   1. Set coords 's attribute named key to value .
3. 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 . A new GeolocationPosition is constructed with EpochTimeStamp timestamp and boolean isHighAccuracy by performing the following steps: Let coords be a newly created GeolocationCoordinates instance: Initialize coord 's latitude attribute to a geographic coordinate in decimal degrees. Initialize coord 's longitude attribute to a geographic coordinate in decimal degrees. 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. Initialize coord 's altitude attribute in meters above the [ WGS84 ] ellipsoid, or null if the implementation cannot provide altitude information. 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. Initialize coord 's speed attribute to a non-negative real number, or as null if the implementation cannot provide speed information. 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 . Return a newly created GeolocationPosition instance with its coords attribute initialized to coords and timestamp accuracyMode attribute initialized to timestamp , and its [[isHighAccuracy]] internal slot set to isHighAccuracy effectiveAccuracy .

PERMISSION_DENIED (numeric value 1)

Candidate Correction: Updated the description of the PERMISSION_DENIED constant to clarify the reasons for permission denial, including non-secure context and user denials. 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.