Please check the errata for any errors or issues reported since publication.
See also translations.
Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This specification defines an API that provides scripted access to geographical location information associated with the hosting device.
Status Update (January 2018): A reference to the GitHub repository was added on 31 January 2018 for comments.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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/.
This document is an edited version of the 2013 Geolocation API Recommendation, and incorporates changes made against the 2013 Recommendation that resolve all the errata. A diff-marked version of this document from the previous Recommendation is also available for comparison purposes. Please note that there is an open issue regarding insecure contexts which is not filed on the Errata yet.
This document was published by the Geolocation Working Group as a Recommendation. If you wish to make comments regarding this document, please use file a bug on GitHub (or send them to public-geolocation@w3.org if you cannot use GitHub (archives). All comments are welcome.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
The group generated an Implementation Report which shows the exit criteria for the Candidate Recommendation have been met. There were at least five User Agent implementations, and all the features of the Geolocation API specification were implemented by two or more User Agents. Also there were at least two Websites that passed the Website Tests.
This document was produced by a group operating under the 5 February 2004 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 1 September 2015 W3C Process Document.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification, as this specification uses that specification's terminology. [WEBIDL]
This section is non-normative.
The Geolocation API defines a high-level interface to location information associated only with the device hosting the implementation, such as latitude and longitude. The API itself is agnostic of the underlying location information sources. 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. No guarantee is given that the API returns the device's actual location.
The API is designed to enable both "one-shot" position requests and repeated position updates, as well as the ability to explicitly query the cached positions. Location information is represented by latitude and longitude coordinates. The Geolocation API in this specification builds upon earlier work in the industry, including [AZALOC], [GEARSLOC], and [LOCATIONAWARE].
The following code extracts illustrate how to obtain basic location information:
Example of a "one-shot" position request.
function showMap(position) { // Show a map centered at (position.coords.latitude, position.coords.longitude). } // One-shot position request. navigator.geolocation.getCurrentPosition(showMap);
Example of requesting repeated position updates.
function scrollMap(position) { // Scrolls the map so that it is centered at (position.coords.latitude, position.coords.longitude). } // Request repeated updates. var watchId = navigator.geolocation.watchPosition(scrollMap); function buttonClickHandler() { // Cancel the updates when the user clicks a button. navigator.geolocation.clearWatch(watchId); }
Example of requesting repeated position updates and handling errors.
function scrollMap(position) { // Scrolls the map so that it is centered at (position.coords.latitude, position.coords.longitude). } function handleError(error) { // Update a div element with error.message. } // Request repeated updates. var watchId = navigator.geolocation.watchPosition(scrollMap, handleError); function buttonClickHandler() { // Cancel the updates when the user clicks a button. navigator.geolocation.clearWatch(watchId); }
Example of requesting a potentially cached position.
// Request a position. We accept positions whose age is not // greater than 10 minutes. If the user agent does not have a // fresh enough cached position object, it will automatically // acquire a new one. navigator.geolocation.getCurrentPosition(successCallback, errorCallback, {maximumAge:600000}); function successCallback(position) { // By using the 'maximumAge' option above, the position // object is guaranteed to be at most 10 minutes old. } function errorCallback(error) { // Update a div element with error.message. }
Forcing the user agent to return a fresh cached position.
// Request a position. We only accept cached positions whose age is not // greater than 10 minutes. If the user agent does not have a fresh // enough cached position object, it will immediately invoke the error // callback. navigator.geolocation.getCurrentPosition(successCallback, errorCallback, {maximumAge:600000, timeout:0}); function successCallback(position) { // By using the 'maximumAge' option above, the position // object is guaranteed to be at most 10 minutes old. // By using a 'timeout' of 0 milliseconds, if there is // no suitable cached position available, the user agent // will asynchronously invoke the error callback with code // TIMEOUT and will not initiate a new position // acquisition process. } function errorCallback(error) { switch(error.code) { case error.TIMEOUT: // Quick fallback when no suitable cached position exists. doFallback(); // Acquire a new position object. navigator.geolocation.getCurrentPosition(successCallback, errorCallback); break; case ... // treat the other error cases. }; } function doFallback() { // No fresh enough cached position available. // Fallback to a default position. }
Forcing the user agent to return any available cached position.
// Request a position. We only accept cached positions, no matter what // their age is. If the user agent does not have a cached position at // all, it will immediately invoke the error callback. navigator.geolocation.getCurrentPosition(successCallback, errorCallback, {maximumAge:Infinity, timeout:0}); function successCallback(position) { // By setting the 'maximumAge' to Infinity, the position // object is guaranteed to be a cached one. // By using a 'timeout' of 0 milliseconds, if there is // no cached position available at all, the user agent // will immediately invoke the error callback with code // TIMEOUT and will not initiate a new position // acquisition process. if (position.timestamp < freshness_threshold && position.coords.accuracy < accuracy_threshold) { // The position is relatively fresh and accurate. } else { // The position is quite old and/or inaccurate. } } function errorCallback(error) { switch(error.code) { case error.TIMEOUT: // Quick fallback when no cached position exists at all. doFallback(); // Acquire a new position object. navigator.geolocation.getCurrentPosition(successCallback, errorCallback); break; case ... // treat the other error cases. }; } function doFallback() { // No cached position available at all. // Fallback to a default position. }
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].
The scope of this specification does not include providing a markup language of any kind.
The scope of this specification does not include defining new URI schemes for building URIs that identify geographic locations.
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. A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that no location information is made available through this API without the user's express permission.
User agents must not send location information to Web sites without the express permission of the user. User agents must acquire permission through a user interface, unless they have prearranged trust relationships with users, as described below. The user interface must include the host component of the document's URI [URI]. Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context [BROWSINGCONTEXT] is navigated to another URL) must be revocable and user agents must respect revoked permissions.
Some user agents will have prearranged trust relationships that do not require such user interfaces. For example, while a Web browser will present a user interface when a Web site performs a geolocation request, a VOIP telephone may not present any user interface when using location information to perform an E911 function.
Recipients must only request location information when necessary. Recipients must only use the location information for the task for which it was provided to them. Recipients must dispose of location information once that task is completed, unless expressly permitted to retain it by the user. Recipients must also take measures to protect this information against unauthorized access. If location information is stored, users should be allowed to update and delete this information.
The recipient of location information must not retransmit the location information without the user’s express permission. Care should be taken when retransmitting and use of encryption is encouraged.
Recipients must 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 may access, update and delete the data, and any other choices that users have with respect to the data. This disclosure must include an explanation of any exceptions to the guidelines listed above.
This section is non-normative.
Further to the requirements listed in the previous section, implementers of the Geolocation API are also advised to consider the following aspects that may negatively affect the privacy of their users: in certain cases, users may inadvertently grant permission to the user agent to disclose their location to Web sites. 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 easy access to interfaces that enable revocation of permissions.
The Geolocation
object is
used by scripts to programmatically determine the location information
associated with the hosting device. The location information is acquired
by applying a user-agent specific algorithm, creating a Position
object, and populating that object
with appropriate data accordingly.
partial interface Navigator { readonly attribute Geolocation geolocation; };
[NoInterfaceObject] interface Geolocation { void getCurrentPosition(PositionCallback successCallback, optional PositionErrorCallback errorCallback, optional PositionOptions options); long watchPosition(PositionCallback successCallback, optional PositionErrorCallback errorCallback, optional PositionOptions options); void clearWatch(long watchId); }; callback PositionCallback = void (Position position); callback PositionErrorCallback = void (PositionError positionError);
The getCurrentPosition()
method takes one, two or three arguments. When called, it must immediately
return and then asynchronously attempt to obtain the current
location of the device. If the attempt is successful,
the successCallback
must be invoked
(i.e. the handleEvent
operation must be called on the
callback object) with a new Position
object,
reflecting the current location of the device. If the attempt
fails, the errorCallback
must be invoked with a
new PositionError
object, reflecting the reason for the failure.
The implementation of the getCurrentPosition
method
must execute the following set of steps:
Position
object, whose age is no greater
than the value of the maximumAge variable, is available,
invoke the successCallback
with the
cached Position
object as a parameter and exit
this set of steps.errorCallback
(if present) with a
new PositionError
object whose code
attribute is set to TIMEOUT and exit this set of steps.enableHighAccuracy
for details).errorCallback
(if present)
with a new PositionError
object
whose code
attribute is set to TIMEOUT, and
exit this set of steps.successCallback
with a new Position
object that reflects the result of the acquisition operation and
exit this set of steps. errorCallback
(if
present) with a new PositionError
object
whose code
is set to POSITION_UNAVAILABLE.The watchPosition()
method takes one, two or three arguments. When called, it must immediately
return a long value that uniquely identifies a watch
operation and then asynchronously start the watch
operation. This operation must first attempt to obtain the current location of the
device. If the attempt is successful, the successCallback
must be invoked
(i.e. the handleEvent
operation must be called on the
callback object) with a new Position
object,
reflecting the current location of the device. If the attempt
fails, the errorCallback
must be invoked with a
new PositionError
object, reflecting the reason for
the failure. The watch operation then must continue
to monitor the position of the device and invoke the appropriate
callback every time this position changes. The watch operation
must continue until
the clearWatch
method is
called with the corresponding identifier.
The implementation of the watch process must execute the following set of steps:
Position
object, whose age is no greater
than the value of the maximumAge variable, is available,
invoke the successCallback
with the
cached Position
object as a parameter.enableHighAccuracy
for details). errorCallback
(if present) with a
new PositionError
object whose code
attribute is set to TIMEOUT and jump to step 6.successCallback
with a
new Position
object that reflects the
result of the acquisition operation. This step may be
subject to callback rate limitation
(see below).errorCallback
(if present)
with a new PositionError
object
whose code
is set to POSITION_UNAVAILABLE. This
step may be subject to callback rate limitation
(see below).In step 5.2.2 of the watch process,
the successCallback
is only invoked when a new position
is obtained and this position differs significantly from the
previously reported position. The definition of what constitutes a
significant difference is left to the implementation. Furthermore,
in steps 5.2.2 and 5.2.3, implementations may impose limitations on
the frequency of callbacks so as to avoid inadvertently consuming a
disproportionate amount of resources.
For both getCurrentPosition
and watchPosition
, the implementation must never invoke
the successCallback
without having first obtained
permission from the user to share location. Furthermore, the
implementation should always obtain the user's permission to share location before
executing any of the getCurrentPosition
or watchPosition
steps
described above. If the user grants permission, the
appropriate callback must be invoked as described above. If the user
denies permission, the errorCallback
(if present)
must be invoked with code
PERMISSION_DENIED, irrespective of any
other errors encountered in the above steps.
The time that is spent obtaining the user permission must not be
included in the period covered by the timeout
attribute
of the PositionOptions
parameter. The timeout
attribute must only apply to the
location acquisition operation.
The clearWatch()
method
takes one argument. When called, it must first check the value of
the given watchId
argument.
If this value does not correspond to any previously started watch
process, then the method must return immediately without taking any
further action. Otherwise, the watch process identified by the
watchId
argument must be immediately stopped and no
further callbacks must be invoked.
The getCurrentPosition()
and watchPosition()
methods accept PositionOptions
objects as their third
argument.
In ECMAScript, PositionOptions
objects are represented using regular native objects with optional
properties named enableHighAccuracy
, timeout
and maximumAge
.
dictionary PositionOptions { boolean enableHighAccuracy = false; [Clamp] unsigned long timeout = 0xFFFFFFFF; [Clamp] unsigned long maximumAge = 0; };
In ECMAScript, the enableHighAccuracy
,
timeout
and maximumAge
properties are all optional: when
creating a PositionOptions object, the developer may specify any of these
properties.
The enableHighAccuracy
attribute provides a hint that the application would like to receive the
best possible results. This may result in slower response times or
increased power consumption. The user might also deny this capability, or
the device might not be able to provide more accurate results than if the
flag wasn't specified. The intended purpose of this attribute is to allow
applications to inform the implementation that they do not require high
accuracy geolocation fixes and, therefore, the implementation can avoid
using geolocation providers that consume a significant amount of power (e.g. GPS).
This is especially useful for applications running on battery-powered devices,
such as mobile phones.
The timeout
attribute denotes
the maximum length of time (expressed in milliseconds) that is
allowed to pass from the call
to getCurrentPosition()
or watchPosition()
until
the corresponding
successCallback
is invoked. If the implementation is unable
to successfully acquire a new Position
before the given timeout elapses, and
no other errors have occurred in this interval, then the corresponding
errorCallback
must be invoked with
a PositionError
object
whose code
attribute is set
to TIMEOUT. Note that the time that is
spent obtaining the user permission is not included in the period
covered by the timeout
attribute. The timeout
attribute only applies to the
location acquisition operation.
In case of a getCurrentPosition()
call, the
errorCallback
would be invoked at most once.
In case of
a watchPosition()
,
the errorCallback
could be invoked repeatedly: the
first timeout is relative to the
moment watchPosition()
was called or the moment the user's permission was obtained, if
that was necessary. Subsequent timeouts are relative to the moment
when the implementation determines that the position of the hosting
device has changed and a new
Position
object must be acquired.
The maximumAge
attribute indicates
that the application is willing to accept a cached position whose age is
no greater than the specified time in milliseconds. If maximumAge
is set to 0, the
implementation must immediately attempt to acquire a new position object.
Setting the maximumAge
to Infinity
must determine the implementation to return a cached position regardless of
its age. If an implementation does not have a cached position available
whose age is no greater than the specified maximumAge
, then it must acquire a new position
object. In case of a watchPosition()
, the maximumAge
refers to the first position object
returned by the implementation.
The Position
interface is the
container for the geolocation information returned by this API. This
version of the specification allows one attribute of type Coordinates
and a
timestamp
. Future versions of the API
may allow additional attributes that provide other information about this
position (e.g. street addresses).
[NoInterfaceObject] interface Position { readonly attribute Coordinates coords; readonly attribute DOMTimeStamp timestamp; };
The coords
attribute contains a set of
geographic coordinates together with their associated accuracy, as well as
a set of other optional attributes such as altitude and speed.
The timestamp
attribute represents
the time when the Position
object was
acquired and is represented as a DOMTimeStamp [DOMTIMESTAMP].
[NoInterfaceObject] interface Coordinates { readonly attribute double latitude; readonly attribute double longitude; readonly attribute double? altitude; readonly attribute double accuracy; readonly attribute double? altitudeAccuracy; readonly attribute double? heading; readonly attribute double? speed; };
The geographic coordinate reference system used by the attributes in this interface is the World Geodetic System (2d) [WGS84]. No other reference system is supported.
The latitude
and longitude
attributes are geographic coordinates
specified in decimal degrees.
The altitude
attribute denotes the
height of the position, specified in meters above the [WGS84] ellipsoid. If the implementation cannot
provide altitude information, the value of this attribute must be null.
The accuracy
attribute denotes the
accuracy level of the latitude and longitude coordinates. It is specified
in meters and must be supported by all implementations. The value of the accuracy
attribute must be a non-negative real number.
The altitudeAccuracy
attribute is specified in meters. If the implementation cannot provide
altitude information, the value of this attribute must be null. Otherwise,
the value of the altitudeAccuracy attribute must be a non-negative real number.
The accuracy
and altitudeAccuracy
values returned by
an implementation should correspond to a 95% confidence level.
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.
If the implementation cannot provide heading information, the value of this
attribute must be null. If the hosting device is stationary (i.e. the value
of the speed
attribute is 0), then the value of the heading
attribute must be NaN.
The speed
attribute denotes the magnitude
of the horizontal component of the hosting device's current velocity and is
specified in meters per second.
If the implementation cannot provide speed information, the value of this
attribute must be null. Otherwise, the value of the speed attribute must be
a non-negative real number.
[NoInterfaceObject] interface PositionError { 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; };
The code
attribute must return the
appropriate code from the following list:
PERMISSION_DENIED
(numeric value 1)
POSITION_UNAVAILABLE
(numeric value 2)
TIMEOUT
(numeric value 3)
timeout
property has elapsed before the implementation could successfully acquire a
new Position
object.
The message
attribute must return an
error message describing the details of the error encountered. This
attribute is primarily intended for debugging and developers should not
use it directly in their application user interface.
Someone visiting a foreign city could access a Web application that allows users to search or browse through a database of tourist attractions. Using the Geolocation API, the Web application has access to the user's approximate position and it is therefore able to rank the search results by proximity to the user's location.
A group of friends is hiking through the Scottish highlands. Some of them write short notes and take pictures at various points throughout the journey and store them using a Web application that can work offline on their hand-held devices. Whenever they add new content, the application automatically tags it with location data from the Geolocation API (which, in turn, uses the on-board GPS device). Every time they reach a town or a village, and they are again within network coverage, the application automatically uploads their notes and pictures to a popular blogging Web site, which uses the geolocation data to construct links that point to a mapping service. Users who follow the group's trip can click on these links to see a satellite view of the area where the notes were written and the pictures were taken. Another example is a life blog where a user creates content (e.g. images, video, audio) that records her every day experiences. This content can be automatically annotated with information such as time, geographic position or even the user's emotional state at the time of the recording.
A user finds herself in an unfamiliar city area. She wants to check her position so she uses her hand-held device to navigate to a Web-based mapping application that can pinpoint her exact location on the city map using the Geolocation API. She then asks the Web application to provide driving directions from her current position to her desired destination.
A mapping application can help the user navigate along a route by providing detailed turn-by-turn directions. The application does this by registering with the Geolocation API to receive repeated location updates of the user's position. These updates are delivered as soon as the implementing user agent determines that the position of the user has changed, which allows the application to anticipate any changes of direction that the user might need to do.
A tour-guide Web application can use the Geolocation API to monitor the user's position and trigger visual or audio notifications when interesting places are in the vicinity. An online task management system can trigger reminders when the user is in the proximity of landmarks that are associated with certain tasks.
A widget-like Web application that shows the weather or news that are relevant to the user's current area can use the Geolocation API to register for location updates. If the user's position changes, the widget can adapt the content accordingly.
A social network application allows its users to automatically tag their status updates with location information. It does this by monitoring the user's position with the Geolocation API. Each user can control the granularity of the location information (e.g. city or neighborhood level) that is shared with the other users. Any user can also track his network of friends and get real-time updates about their current location.
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, Aza Raskin, Carl Reed, Thomas Roessler, Dirk Segers, Allan Thomson, Martin Thomson, Doug Turner, Erik Wilde, Matt Womer, Mohamed Zergaoui