See also translations.
Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
The Geolocation API provides access to geographical location information associated with the hosting device.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
The Devices and Sensors Working Group is updating this specification in the hope of making it a "living standard". As such, we've dropped the "Editions" and aim to continue publishing updated W3C Recommendations of this specification as we add new features or fix bugs.
This document was published by the Devices and Sensors Working Group as a Recommendation using the Recommendation track.
W3C recommends the wide deployment of this specification as a standard for the Web.
A W3C Recommendation is a specification that, after extensive consensus-building, is endorsed by W3C and its Members, and has commitments from Working Group members to royalty-free licensing for implementations. Future updates to this Recommendation may incorporate new features.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 2 November 2021 W3C Process Document.
This section is non-normative.
The Geolocation API defines a high-level interface to location information associated only with the device hosting the implementation. 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. 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.
If an end user grants permission, the Geolocation API:
GeolocationPosition
interface.
getCurrentPosition
()
method and the ability to receive
updates for when the position of the hosting device significantly
changes via the watchPosition
()
method.
PositionOptions
's maximumAge
,
allows an application to request a cached position whose age is no
greater than a specified value (only the last position is cached).
GeolocationPositionError
, that have occurred while acquiring a position.
enableHighAccuracy
, supports
requesting "high accuracy" position data, though the request can be
ignored by the user agent.
This section is non-normative.
This specification is limited to providing a scripting API for retrieving geographic position information associated with a hosting device. The geographic position information is provided in terms of 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.
This section is non-normative.
Since First Public Working Draft in 2021, the Geolocation API has received the following normative changes:
Since publication of the Second Edition in 2016, this specification has received the following changes:
errorCallback
is now nullable.
callbacks
are no longer treated as "EventHandler" objects
(i.e., objects that have a .handleEvent()
method), but are now
exclusively treated as IDL callback functions.
[NoInterfaceObject]
, so Geolocation
and other interface of this
spec are now in the global scope. Also, the interfaces were renamed
from NavigatorGeolocation*
to just Geolocation*
.
See the commit history for a complete list of changes.
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.
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.
This section is non-normative.
Stop watching for position changes by calling the
clearWatch
()
method.
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.
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. In this example, we accept a position whose age is no greater than 10 minutes. If the user agent does not have a fresh enough cached position object, it automatically acquires a new position.
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.
This section is non-normative.
The default allowlist of 'self'
allows Geolocation 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"
attribute to an iframe
element:
Alternatively, the API can be disabled in a first-party context by specifying an HTTP response header:
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.
This section is non-normative.
The Geolocation API is a powerful feature that
requires express permission from an end-user before any location
data is shared with a web application. This requirement is
normatively enforced by the check permission steps on which the
getCurrentPosition
()
and
watchPosition
()
methods rely.
An end-user will generally give express permission through a user interface, which usually present a range of permission lifetimes that the end-user can choose from. The choice of lifetimes vary across user agents, but they are typically time-based (e.g., "a day"), or until browser is closed, or the user might even be given the choice for the permission to be granted indefinitely. The permission lifetimes dictate how long a user agent grants a permission before that permission is automatically reverted back to its default permission state, prompting the end-user to make a new choice upon subsequent use.
Although the granularity of the permission lifetime varies across user-agents, this specification urges user agents to limit the lifetime to a single browsing session by default (see 3.4 Checking permission to use the API for normative requirements).
This section is non-normative.
This section applies to "recipients", which generally means developers utilizing the Geolocation API. 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.
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.
The Geolocation API is a default powerful feature
identified by the name "geolocation"
.
When checking permission to use the API, a user agent MAY 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.
There are no security considerations associated with Geolocation API at the time of publication. However, readers are advised to read the 3. Privacy considerations.
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 |
---|---|
[[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:
Document
is not fully active:
POSITION_UNAVAILABLE
.
The watchPosition
(successCallback,
errorCallback, options)
method steps are:
Document
is not fully active:
POSITION_UNAVAILABLE
.
unsigned long
that is greater than zero.
[[watchIDs]]
.
When clearWatch()
is invoked, the user agent MUST:
[[watchIDs]]
.
To request a position, pass a PositionCallback
successCallback, a PositionErrorCallback?
errorCallback, PositionOptions
options, and an optional watchId:
[[watchIDs]]
.
Document
.
PERMISSION_DENIED
.
PermissionDescriptor
whose
name
is "geolocation"
.
PERMISSION_DENIED
.
To acquire a position,
passing PositionCallback
successCallback, a
PositionErrorCallback?
errorCallback,
PositionOptions
options, and an optional
watchId.
[[watchIDs]]
does not contain watchId,
terminate this algorithm.
EpochTimeStamp
that represents now.
timeout
.
[[cachedPosition]]
.
"geolocation"
.
maximumAge
is greater than 0:
maximumAge
member.
timestamp
's value is greater than
cacheTime, and
cachedPosition.[[isHighAccuracy]]
equals options.enableHighAccuracy
,
set position to cachedPosition.
enableHighAccuracy
during
acquisition.
GeolocationPosition
passing acquisitionTime and
options.enableHighAccuracy
.
[[cachedPosition]]
to
position.
Call back with error passing errorCallback and
PERMISSION_DENIED
.
TIMEOUT
.
POSITION_UNAVAILABLE
.
When instructed to call back with error, given an
PositionErrorCallback?
callback and an
unsigned short
code:
GeolocationPositionError
instance whose
code
attribute is initialized to code.
WebIDLdictionary PositionOptions
{
boolean enableHighAccuracy
= false;
[Clamp] unsigned long timeout
= 0xFFFFFFFF;
[Clamp] unsigned long maximumAge
= 0;
};
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 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.
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 EpochTimeStamp timestamp
;
};
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:
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.
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
;
};
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:
GeolocationCoordinates
instance:
latitude
attribute to a geographic coordinate in decimal degrees.
longitude
attribute to a geographic coordinate in decimal degrees.
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.
altitude
attribute in meters above the [WGS84] ellipsoid, or null
if
the implementation cannot provide altitude information.
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.
speed
attribute to a non-negative real number, or as null
if the
implementation cannot provide speed information.
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
.
GeolocationPosition
instance with its
coords
attribute initialized to coords and
timestamp
attribute initialized to
timestamp, and its [[isHighAccuracy]]
internal slot set to isHighAccuracy.
WebIDL[Exposed=Window]
interface GeolocationPositionError
{
const unsigned short PERMISSION_DENIED
= 1;
const unsigned short TIMEOUT
= 3;
readonly attribute unsigned short code
;
readonly attribute DOMString message
;
};
PERMISSION_DENIED
(numeric value 1)
POSITION_UNAVAILABLE
(numeric value 2)
TIMEOUT
(numeric value 3)
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.
The Geolocation API defines a policy-controlled feature identified by the token string "geolocation"
. Its
default allowlist is 'self'
.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
WebIDLpartial interface Navigator {
[SameObject] readonly attribute Geolocation
geolocation
;
};
[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
);
dictionary PositionOptions
{
boolean enableHighAccuracy
= false;
[Clamp] unsigned long timeout
= 0xFFFFFFFF;
[Clamp] unsigned long maximumAge
= 0;
};
[Exposed=Window, SecureContext]
interface GeolocationPosition
{
readonly attribute GeolocationCoordinates
coords
;
readonly attribute EpochTimeStamp timestamp
;
};
[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
;
};
[Exposed=Window]
interface GeolocationPositionError
{
const unsigned short PERMISSION_DENIED
= 1;
const unsigned short POSITION_UNAVAILABLE
= 2;
const unsigned short TIMEOUT
= 3;
readonly attribute unsigned short code
;
readonly attribute DOMString message
;
};
accuracy
attribute for GeolocationCoordinates
§9.1altitude
attribute for GeolocationCoordinates
§9.2altitudeAccuracy
attribute for GeolocationCoordinates
§9.2[[cachedPosition]]
internal slot for Geolocation
§6.1clearWatch()
method for Geolocation
§6.4code
attribute for GeolocationPositionError
§10.2coords
attribute for GeolocationPosition
§8.1enableHighAccuracy
member for PositionOptions
§7.1geolocation
attribute for Navigator
§5.Geolocation
interface
§6."geolocation"
§3.4GeolocationCoordinates
interface
§9.GeolocationPosition
interface
§8.GeolocationPositionError
interface
§10.getCurrentPosition
method for Geolocation
§6.2heading
attribute for GeolocationCoordinates
§9.3[[isHighAccuracy]]
internal slot for GeolocationPosition
§8.3latitude
attribute for GeolocationCoordinates
§9.1longitude
attribute for GeolocationCoordinates
§9.1maximumAge
member for PositionOptions
§7.3message
attribute for GeolocationPositionError
§10.3PERMISSION_DENIED
§10.1POSITION_UNAVAILABLE
§10.1PositionCallback
§6.PositionErrorCallback
§6.PositionOptions
dictionary
§7.speed
attribute for GeolocationCoordinates
§9.4timeout
member for PositionOptions
§7.2TIMEOUT
§10.1timestamp
attribute for GeolocationPosition
§8.2[[watchIDs]]
internal slot for Geolocation
§6.1watchPosition
method for Geolocation
§6.3This section is non-normative.
This specification builds upon earlier work in the industry, including research by Aza Raskin, Google Gears Geolocation API, and LocationAware.org.
Thanks also to Alec Berntson, Alissa Cooper, Steve Block, Greg Bolsinga, Lars Erik Bolstad, Aaron Boodman, Dave Burke, Chris Butler, Max Froumentin, Shyam Habarakada, Marcin Hanclik, Ian Hickson, Brad Lassey, Angel Machin, Cameron McCormack, Daniel Park, Stuart Parmenter, Olli Pettay, Chris Prince, Arun Ranganathan, Carl Reed, Thomas Roessler, Dirk Segers, Allan Thomson, Martin Thomson, Doug Turner, Erik Wilde, Matt Womer, and Mohamed Zergaoui.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: