Geolocation

This section is non-normative.

The API is designed to enable both "one-shot" position requests and repeated position updates. The following examples illustrate common use cases.

This section is non-normative.

Request the user's current location. If the user allows it, you will get back a position object. The website can influence the position's accuracy by using the accuracyMode option. By default, the user agent will provide a "precise" location, but a website can request an "approximate" location if it doesn't require high accuracy, which helps protect user privacy.

Example 1 : A one-shot position request

navigator.geolocation.getCurrentPosition(position => {
  const { latitude, longitude } = position.coords;
  // Show a map centered at latitude / longitude.
});

Example 2 : Requesting an approximate position

navigator.geolocation.getCurrentPosition(position => {  const { latitude, longitude } = position.coords;  // Use the approximate location for city-level features, like showing weather.
},
console.error,
{

accuracyMode
:
"approximate"

});

This section is non-normative.

Request the ability to watch user's current location. If the user allows it, you will get back continuous updates of the user's position.

Example 2 3 : Watching a position for repeated updates

const watchId = navigator.geolocation.watchPosition(position => {
  const { latitude, longitude } = position.coords;
  // Show a map centered at latitude / longitude.
});

This section is non-normative.

Stop watching for position changes by calling the clearWatch () method.

Example 3 4 : Using clearWatch()

const watchId = navigator.geolocation.watchPosition(
  position => console.log(position);
);
function buttonClickHandler() {
  // Cancel the updates when the user clicks a button.
  navigator.geolocation.clearWatch(watchId);
}

And a HTML button that when pressed stops watching the position.

<button onclick="buttonClickHandler()">
  Stop watching location

</

button

>

This section is non-normative.

When an error occur, the second argument of the watchPosition () or getCurrentPosition () method gets called with a GeolocationPositionError error, which can help you figure out what might have gone wrong.

Example 4 5 : Handling errors

// Request repeated updates.
const watchId = navigator.geolocation.watchPosition(
  scrollMap, handleError
);
function scrollMap(position) {
  const { latitude, longitude } = position.coords;
  // Scroll map to latitude / longitude.
}
function handleError(error) {
  // Display error based on the error code.
  const { code } = error;
  switch (code) {
    case GeolocationPositionError.TIMEOUT:
      // Handle timeout.
      break;
    case GeolocationPositionError.PERMISSION_DENIED:
      // User denied the request.
      break;
    case GeolocationPositionError.POSITION_UNAVAILABLE:
      // Position not available.
      break;
  }
}

This section is non-normative.

By default, the API always attempts to return a cached position so long as it has a previously acquired ~~position.~~ position that matches the requested accuracyMode. In this example, we accept a precise position whose age is no greater than 10 minutes. If the user agent does not have a fresh enough cached position ~~object,~~ object of the correct accuracy, it automatically acquires a new position.

Example 5 6 : Getting a cached precise position

navigator.geolocation.getCurrentPosition(
  successCallback,
  console.error,
  {  }

  { maximumAge: 600_000 } // `accuracyMode` defaults to "precise"

);
function successCallback(position) {
  // By using the 'maximumAge' member above, the position
  // object is guaranteed to be at most 10 minutes old.
}

Similarly, you can request a cached approximate position.

Example 7 : Getting a cached approximate position

navigator.geolocation.getCurrentPosition(
  successCallback,
  console.error,
  { maximumAge: 600_000, accuracyMode: "approximate" }
);
function successCallback(position) {  // This position is approximate and at most 10 minutes old.
}

This section is non-normative.

If you require location information in a time sensitive manner, you can use the PositionOptions timeout member to limit the amount of time you are willing to wait to acquire a position .

Example 6 8 : Timing out a position request

// Request a position. We are only willing to wait 10
// seconds for it.
navigator.geolocation.getCurrentPosition(
  successCallback,
  errorCallback,
  { timeout: 10_000 }
);
function successCallback(position) {
  // Request finished in under 10 seconds...
}
function errorCallback(error) {
  switch (error.code) {
    case GeolocationPositionError.TIMEOUT:
      // We didn't get it in a timely fashion.
      doFallback();
      // Acquire a new position object,
      // as long as it takes.
      navigator.geolocation.getCurrentPosition(
        successCallback, errorCallback
      );
      break;
    case "...": // treat the other error cases.
  }
}

function


doFallback

(


)
{}

This section is non-normative.

The default allowlist of 'self' allows API usage in same-origin nested frames but prevents third-party content from using the API.

Third-party usage can be selectively enabled by adding the allow ="geolocation" or allow="geolocation-approximate" attribute to an iframe ~~element:~~ element. Note that if geolocation is allowed, geolocation-approximate is also implicitly allowed.

Example 7 9 : Enabling Geolocation in an iframe

<!-- This allows both precise and approximate geolocation -->
<iframe
  src="https://third-party.com"
  allow="geolocation">
</iframe>
<!-- This allows only approximate geolocation -->
<iframe
  src="https://another-third-party.com"
  allow="geolocation-approximate">

</

iframe

>

Alternatively, the API can be disabled in a first-party context by specifying an HTTP response ~~header:~~ header. Disabling geolocation-approximate will also disable geolocation.

Example 8 10 : Permissions Policy over HTTP



Permissions-Policy

:

geolocation=()

geolocation-approximate=()

See Permissions Policy for more details about the Permissions-Policy HTTP header.

This section is non-normative.

The API defined in this specification is used to retrieve the geographic location of a hosting device. In almost all cases, this information also discloses the location of the user of the device, thereby potentially compromising the user's privacy.

To mitigate this privacy risk, this specification introduces the accuracyMode option, which allows the application to request an approximate position . This allows applications to function without needing the user's precise position , thus offering a more privacy-friendly alternative. When an application requests an approximate position , the user agent can provide a less precise location that still meets the application's needs while protecting the user's precise position . Even when a precise position is requested, the user agent can provide an approximate position instead, for example, if the user has only granted permission for approximate accuracy.

This section is non-normative.

Note : Developers' responsibility with this sensitive data

This section applies to "recipients", which generally means developers utilizing Geolocation . Although it's impossible for the user agent, or this specification, to enforce these requirements, developers need to read this section carefully and do their best to adhere to the suggestions below. Developers need to be aware that there might be privacy laws in their jurisdictions that can govern the usage and access to users' location data.

Recipients ought to only request position information when necessary, and only use the location information for the task for which it was provided to them. Recipients ought to dispose of location information once that task is completed, unless expressly permitted to retain it by the user. Recipients need to also take measures to protect this information against unauthorized access. If location information is stored, users need to be allowed to update and delete this information.

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 should request an approximate position by setting the accuracyMode option to "approximate". This is preferable to requesting a precise position , which is done by either setting accuracyMode to "precise" or by leaving the option unset. 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 permission. Care needs to be taken when retransmitting and the use of encryption is encouraged.

Recipients ought to clearly and conspicuously disclose the fact that they are collecting location data, the purpose for the collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, update and delete the data, and any other choices that users have with respect to the data. This disclosure needs to include an explanation of any exceptions to the guidelines listed above.

This section is non-normative.

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. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are advised to enable user awareness of location sharing, and to provide access to user interfaces that enable revocation of permissions.

Geolocation is a default powerful feature identified by the name s "geolocation" . for precise position and "geolocation-approximate" for approximate position .

~~When checking~~ To request geolocation permission for a given PermissionDescriptordescriptor, the user agent MUST run the following steps. These steps override the default behavior of request permission to use for these features.

If descriptor.name is "geolocation":
1. Prompt the user to choose between granting permission for precise position , granting permission for approximate position , or denying permission.
2. If the user grants permission for precise position :
  1. Set the permission state of "geolocation" to "granted".
  2. Set the permission state of "geolocation-approximate" to "granted".
  3. Return "granted".
3. If the user grants permission for approximate position :
  1. Set the permission state of "geolocation-approximate" to "granted".
  2. Return "prompt".
4. If the ~~API, a~~ user denies permission:
  1. Set the permission state of "geolocation" to "denied".
  2. Set the permission state of "geolocation-approximate" to "denied".
  3. Return "denied".
If descriptor.name is "geolocation-approximate":
1. Prompt the user to choose between granting permission for approximate position or denying permission.
2. If the user grants permission for approximate position :
  1. Set the permission state of "geolocation-approximate" to "granted".
  2. Return "granted".
3. If the user denies permission:
  1. Set the permission state of "geolocation" to "denied".
  2. Set the permission state of "geolocation-approximate" to "denied".
  3. Return "denied".

A user agent MAY also suggest time-based permission lifetimes , such as "24 hours", "1 week", or choose to remember the permission grant indefinitely. However, it is RECOMMENDED that a user agent prioritize restricting the permission lifetime to a single session: This can be, for example, until the realm is destroyed, the end-user navigates away from the origin , or the relevant browser tab is closed.

A malicious actor could potentially infer a user's precise position by collecting and correlating multiple, distinct approximate position s. 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.

WebIDL[Exposed=Window]
interface Geolocation {
  undefined getCurrentPosition (
    PositionCallback successCallback,
    optional PositionErrorCallback? errorCallback = null,
    optional PositionOptions options = {}
  );
  long watchPosition (
    PositionCallback successCallback,
    optional PositionErrorCallback? errorCallback = null,
    optional PositionOptions options = {}
  );
  undefined clearWatch (long watchId);
};
callback PositionCallback = undefined (
  GeolocationPosition position
);
callback PositionErrorCallback = undefined (
  GeolocationPositionError positionError
);

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

Internal slot	Description
[[cachedPrecisePosition]]	A `GeolocationPosition`, initialized to null. It's a reference to the last acquired precise position and serves as a cache. A user agent MAY evict `[[cachedPrecisePosition]]` by resetting it to null at any time for any reason.
[[cachedApproximatePosition]]	A `GeolocationPosition`, initialized to null. It's a reference to the last acquired approximate position and serves as a cache. A user agent MAY evict `[[cachedApproximatePosition]]` by resetting it to null at any time for any reason.
~~[[cachedPosition]]~~	A `GeolocationPosition` , initialized to null. It's a reference to the last acquired position and serves as a cache. A user agent MAY evict `[[cachedPosition]]` by resetting it to null at any time for any reason.
[[watchIDs]]	Initialized as an empty list of `unsigned long` items .

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

Candidate Correction: Updated reference to the global object to use 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.
Request a position passing this , successCallback, errorCallback, and options.

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

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.
Let watchId be an implementation-defined unsigned long that is greater than zero.
Append watchId to this 's [[watchIDs]] .
Request a position passing this , successCallback, errorCallback, options, and watchId.
Return watchId.

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

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:

Let watchIDs be geolocation 's [[watchIDs]] .
Let document be the geolocation 's relevant global object 's associated Document .
Let permissionName be "geolocation-approximate" if options.accuracyMode is "approximate", otherwise let it be "geolocation".
If document is not allowed to use the ~~"geolocation"~~ permissionName feature:
1. If watchId was passed, remove watchId from watchIDs.
2. Call back with error passing errorCallback and PERMISSION_DENIED .
3. Terminate this algorithm.
Candidate Correction: Added missing step to handle non-secure contexts .
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.
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.
Let descriptor be a new PermissionDescriptor whose name is ~~"geolocation" .~~ permissionName.
In parallel :
1. Set permission to request geolocation permission ~~to use~~ for descriptor.
2. Let handle permission denial ~~is "denied", then:~~ be the following steps:
  1. If watchId was passed, remove watchId from watchIDs.
  2. Call back with error passing errorCallback and PERMISSION_DENIED .
  3. Terminate this algorithm.
3. If permission is "denied":
  1. If options.accuracyMode is "approximate", then run handle permission denial.
  2. Otherwise:
    1. Let approximatePermission be get the current permission state of "geolocation-approximate".
    2. If approximatePermission is "denied", then run handle permission denial.
4. Wait to acquire a position passing successCallback, errorCallback, options, and watchId.
5. If watchId was not passed, terminate this algorithm.
6. 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
    
    The desired effect here being that position updates are exclusively delivered to fully active documents that are visible; Otherwise the updates get silently "dropped on the floor". Only once a document again becomes fully active and visible (e.g., an iframe gets reattached to a parent document), do the position updates once again start getting delivered.
  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.

If watchId was passed and this 's [[watchIDs]] does not contain watchId, terminate this algorithm.
Let acquisitionTime be a new EpochTimeStamp that represents now.
Let timeoutTime be the sum of acquisitionTime and options. timeout .
~~Let cachedPosition be this 's [[cachedPosition]] .~~ 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 precisePermission be get the current permission state of "geolocation".
2. Let approximatePermission be get the current permission state of "geolocation-approximate".
3. Let effectiveAccuracy be null.
4. If options. "geolocation" accuracyMode . is "approximate":
  1. If approximatePermission is "granted", set effectiveAccuracy to "approximate".
5. Otherwise, if options.accuracyMode is "precise":
  1. If permission precisePermission is ~~"denied":~~ "granted", set effectiveAccuracy to "precise".
  2. Otherwise, if approximatePermission is "granted", set effectiveAccuracy to "approximate".
6. If effectiveAccuracy is null:
  1. Stop timeout.
  2. Do the user or system denied permission failure case step.
  3. Terminate this algorithm.
7. ~~If permission is "granted":~~
  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 :
      
      Call back with error passing errorCallback and emulatedPositionData. code .
      
      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.
8. Let cachedPosition be null.
9. If effectiveAccuracy is "precise":
  1. Set cachedPosition to this 's [[cachedPrecisePosition]].
10. Otherwise, if effectiveAccuracy is "approximate":
  1. Set cachedPosition to this 's [[cachedApproximatePosition]].
11. Let position be null.
12. 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 is "approximate" or ( effectiveAccuracy is "precise" 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.
13. 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.~~ .
14. 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.
15. 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:
    
    "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.
    
    "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.
    
    "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.
    
    "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.
    
    "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.
    
    "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.
  2. Set position to a new GeolocationPosition passing positionData, acquisitionTime and, options. enableHighAccuracy . , and effectiveAccuracy.
  3. If effectiveAccuracy is "precise":
    1. Set this 's [[cachedPosition]] [[cachedPrecisePosition]] to position.
  4. Otherwise, if effectiveAccuracy is "approximate":
    1. Set this 's [[cachedApproximatePosition]] to position.
  Set position to a new GeolocationPosition passing acquisitionTime and options. enableHighAccuracy .
  
  Set this 's [[cachedPosition]] to position.
16. Stop the timeout.
17. 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 On certain platforms, there can be a circumstance where the user has granted the user agent permission to use Geolocation at the browser-level, but the permission to access location services has been denied at the OS level. 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:

If callback is null, return.
Let error be a newly created GeolocationPositionError instance whose code attribute is initialized to code.
Queue a task on the geolocation task source with a step that invokes callback with « error » and " report ".

WebIDLenum 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. 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".

Note : Interaction with enableHighAccuracy

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).

Note : A word of warning about enableHighAccuracy

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

Note : When is the timeout calculated?

The time spent waiting for the document to become visible and for obtaining permission to use the API is not included in the period covered by the timeout member. The timeout member only applies when acquiring a position begins.

Note : Immediate cancellation

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.

]

WebIDL[Exposed=Window, SecureContext]
interface GeolocationPosition {
  readonly attribute GeolocationCoordinates coords;
  readonly attribute

  readonly attribute EpochTimeStamp timestamp;
  readonly attribute AccuracyMode accuracyMode;

  [Default] object toJSON();
};

The coords attribute contains geographic coordinates.

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

The accuracyMode 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 obtain the position.

Candidate Addition: Introduce a


toJSON()

method to allow the


GeolocationPosition

object to be easily converted into a JSON representation, facilitating interoperability and ease of use in web applications.

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

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

Internal slot	Description
[[isHighAccuracy]]	A `boolean` that records the value of the `enableHighAccuracy` member when this `GeolocationPosition` is created .

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 .

WebIDL[Exposed=Window, SecureContext]
interface GeolocationCoordinates {
  readonly attribute double accuracy;
  readonly attribute double latitude;
  readonly attribute double longitude;
  readonly attribute double? altitude;
  readonly attribute double? altitudeAccuracy;
  readonly attribute double? heading;
  readonly attribute double? speed;
  [Default] object toJSON();
};

MDN ✅

GeolocationCoordinates/accuracy

This feature is in all major engines.

Chrome	5+
Chrome Android	?
Edge	12+
Edge Mobile	?
Firefox	3.5+
Firefox Android	?
Opera	?
Opera Android	?
Safari	5+
Safari iOS	3+
Samsung Internet	?
WebView Android	37+

MDN ✅

GeolocationCoordinates/latitude

This feature is in all major engines.

Chrome	5+
Chrome Android	?
Edge	12+
Edge Mobile	?
Firefox	3.5+
Firefox Android	?
Opera	?
Opera Android	?
Safari	5+
Safari iOS	3+
Samsung Internet	?
WebView Android	37+

MDN ✅

GeolocationCoordinates/longitude

This feature is in all major engines.

Chrome	5+
Chrome Android	?
Edge	12+
Edge Mobile	?
Firefox	3.5+
Firefox Android	?
Opera	?
Opera Android	?
Safari	5+
Safari iOS	3+
Samsung Internet	?
WebView Android	37+

~~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 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.

Candidate Addition: Extend the


toJSON()

method functionality to the


GeolocationCoordinates

object, allowing it to be serialized into a JSON format which enhances data handling and integration capabilities in web applications.

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

A new GeolocationPosition is constructed with map positionData, EpochTimeStamp timestamp and, boolean isHighAccuracy, and string effectiveAccuracy by performing the following steps:

Let coords be a newly created GeolocationCoordinates instance.
For each key → value in positionData:
1. Set coords 's attribute named key to value.
Return a newly created GeolocationPosition instance with its coords attribute initialized to coords and, timestamp attribute initialized to timestamp, accuracyMode attribute initialized to effectiveAccuracy, 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 attribute initialized to timestamp, and its [[isHighAccuracy]] internal slot set to isHighAccuracy.

A new GeolocationPosition §9.6
accuracy attribute for GeolocationCoordinates §9.1
accuracyMode
- member for PositionOptions §7.1
- attribute for GeolocationPosition §8.3
AccuracyMode enum §7.
acquire a position §6.6
altitude attribute for GeolocationCoordinates §9.2
altitudeAccuracy attribute for GeolocationCoordinates §9.2
"approximate" enum value for AccuracyMode §7.
approximate location information source §1.
approximate position §1.
[[cachedApproximatePosition]] internal slot for Geolocation §6.1
[[cachedPosition]] internal slot for Geolocation §6.1
[[cachedPrecisePosition]] internal slot for Geolocation §6.1
call back with error §6.7
~~checking~~ Checking permission to use the API §3.4
clearWatch() method for Geolocation §6.4
code attribute for GeolocationPositionError §10.2
coords attribute for GeolocationPosition §8.1
emulated position data §12.
enableHighAccuracy member for PositionOptions ~~§7.1~~ §7.2
geolocation attribute for Navigator §5.
Geolocation interface §6.
geolocation task source ~~§8.5~~ §8.6
"geolocation-approximate" §3.4
"geolocation" §3.4
GeolocationCoordinates interface §9.
GeolocationPosition interface §8.
GeolocationPositionError interface §10.
get emulated position data §12.
getCurrentPosition method for Geolocation §6.2
heading attribute for GeolocationCoordinates §9.3
[[isHighAccuracy]] internal slot for GeolocationPosition ~~§8.4~~ §8.5
latitude attribute for GeolocationCoordinates §9.1
location information source §1.
longitude attribute for GeolocationCoordinates §9.1
maximumAge member for PositionOptions ~~§7.3~~ §7.4
message attribute for GeolocationPositionError §10.3
PERMISSION_DENIED §10.1
POSITION_UNAVAILABLE §10.1
PositionCallback §6.
PositionErrorCallback §6.
PositionOptions dictionary §7.
"precise" enum value for AccuracyMode §7.
precise position §1.
request a position §6.5
request geolocation permission §3.4
set emulated position data §12.
speed attribute for GeolocationCoordinates §9.4
timeout member for PositionOptions ~~§7.2~~ §7.3
TIMEOUT §10.1
timestamp attribute for GeolocationPosition §8.2
toJSON()
- method for GeolocationPosition ~~§8.3~~ §8.4
- method for GeolocationCoordinates §9.5
[[watchIDs]] internal slot for Geolocation §6.1
watchPosition method for Geolocation §6.3

[ HR-TIME ] defines the following:
- EpochTimeStamp
[ HTML ] defines the following:
- allow attribute (for iframe element)
- allowed to use
- associated Document
- current settings object
- environment settings object
- fully active (for Document )
- iframe element
- In parallel
- navigable
- navigates
- Navigator interface
- node navigable
- non-secure contexts
- origin
- page visibility change steps
- Queue a task
- realm (for environment settings object)
- relevant global object
- task source
- top-level traversable
- top-level traversable (for navigable )
- visibility state (for Document )
[ INFRA ] defines the following:
- Append (for list )
- contains (for list )
- For each (for map )
- implementation-defined
- item (for list )
- list
- map
- Remove (for list )
- User agents
[ PERMISSIONS ] defines the following:
- default powerful feature
- express permission
- get the current permission state
- grants (for permission )
- lifetimes (for permission )
- name (for powerful feature)
- name (for PermissionDescriptor )
- permission
- permission state
- PermissionDescriptor
- powerful feature
- request permission to use
[ PERMISSIONS-POLICY ] defines the following:
- 'self' (for default allowlist)
- default allowlist (for policy-controlled feature)
- policy-controlled ~~feature~~ features
[ WEBIDL ] defines the following:
- boolean type
- [Clamp] extended attribute
- [Default] extended attribute
- DOMString interface
- double type
- [Exposed] extended attribute
- invokes
- long type
- object type
- [SameObject] extended attribute
- [SecureContext] extended attribute
- this
- undefined type
- unsigned long type
- unsigned short type

Geolocation

Abstract

Status of This Document

1. Introduction

1.1 Scope

2. Examples

2.1 Get current position

2.2 Watch a position

2.3 Stop watching a position

2.4 Handling errors

2.5 Using maximumAge as cache control

2.6 Using timeout

2.7 Enabling the API in third-party contexts

3. Privacy considerations

3.1 User consent

3.2 Privacy considerations for recipients of location information

3.3 Implementation considerations

3.4 Checking permission to use the API

3.5 Preventing Precise Location Reconstruction

4. Security considerations

5. Extensions to the Navigator interface

6. Geolocation interface and callbacks

6.1 Internal slots

6.2 getCurrentPosition() method

6.3 watchPosition() method

6.4 clearWatch() method

6.5 Request a position

6.6 Acquire a position

6.7 Call back with error

7. PositionOptions dictionary

7.1 accuracyMode member

7.2 enableHighAccuracy member

7.2 7.3 timeout member

7.3 7.4 maximumAge member

8. GeolocationPosition interface

8.1 coords attribute

8.2 timestamp attribute

8.3 accuracyMode attribute

8.4 toJSON() method

8.4 8.5 Internal slots

8.5 8.6 Task sources

9. GeolocationCoordinates interface

9.1 latitude , longitude , and accuracy attributes

9.2 altitude and altitudeAccuracy attributes

9.3 heading attribute

9.4 speed attribute

9.5 toJSON() method

9.6 Constructing a GeolocationPosition

10. GeolocationPositionError interface

10.1 Constants

10.2 code attribute

10.3 message attribute

11. Permissions policy

12. Emulation

13. Conformance

A. IDL Index

B. Index

B.1 Terms defined by this specification

B.2 Terms defined by reference

C. Acknowledgments

D. Change log

E. References

E.1 Normative references

2.5 Using `maximumAge` as cache control

2.6 Using `timeout`

5. Extensions to the `Navigator` interface

6. `Geolocation` interface and callbacks

6.2 `getCurrentPosition()` method

6.3 `watchPosition()` method

6.4 `clearWatch()` method

7. `PositionOptions` dictionary

7.1 `accuracyMode` member

7.2 `enableHighAccuracy` member

7.2 7.3 `timeout` member

7.3 7.4 `maximumAge` member

8. `GeolocationPosition` interface

8.1 `coords` attribute

8.2 `timestamp` attribute

8.3 `accuracyMode` attribute

8.4 `toJSON()` method

9. `GeolocationCoordinates` interface

9.1 `latitude`, `longitude`, and `accuracy` attributes

9.2 `altitude` and `altitudeAccuracy` attributes

9.3 `heading` attribute

9.4 `speed` attribute

9.5 `toJSON()` method

9.6 Constructing a `GeolocationPosition`

10. `GeolocationPositionError` interface

10.2 `code` attribute

10.3 `message` attribute