Please refer to the errata for this document, which may include some normative corrections.
See also translations .
Copyright
©
2008-2013
2008-2015
W3C
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
),
All
Rights
Reserved.
).
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.
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 http://www.w3.org/TR/.
This
document
has
been
reviewed
by
W3C
Members,
by
software
developers,
and
by
other
W3C
groups
and
interested
parties,
and
is
endorsed
governed
by
the
Director
as
a
14
October
2005
W3C
Recommendation.
It
is
Process
Document
.
This
Proposed
Edited
Recommendation
reflects
changes
made
as
a
stable
result
of
comments
received
since
the
Recommendation
was
first
published.
This
document
and
may
be
used
as
reference
material
or
cited
from
another
document.
W3C's
role
in
making
incorporates
changes
made
against
the
Recommendation
is
to
draw
attention
to
of
24
October
2013
that
resolve
all
the
specification
and
to
promote
its
widespread
deployment.
This
enhances
errata
known
at
the
functionality
and
interoperability
date
of
publication.
A
diff-marked
version
of
this
document
from
the
Web.
previous
Recommendation
is
also
available
for
comparison
purposes.
By
publishing
this
Recommendation,
W3C
expects
that
This
document
was
published
by
the
Geolocation
Working
Group
as
a
Proposed
Edited
Recommendation
on
28
May
2015.
it
merged
all
the
errata
known
at
the
date
of
publication
into
the
functionality
specified
in
this
Geolocation
API
v1
Recommendation,
which
was
published
on
October
24,
2013.This
document
is
intended
to
become
a
W3C
Recommendation.
Publication
as
a
Proposed
Edited
Recommendation
will
does
not
imply
endorsement
by
the
W3C
Membership.
This
is
a
draft
document
and
may
be
affected
updated,
replaced
or
obsoleted
by
changes
other
documents
at
any
time.
It
is
inappropriate
to
HTML5
or
Web
IDL
cite
this
document
as
those
specifications
proceed
to
Recommendation.
other
than
work
in
progress.
This
document
incorporates
minor
changes
made
against
the
W3C
Advisory
Committee
Members
are
invited
to
send
formal
review
comments
on
this
Proposed
Edited
Recommendation
to
the
W3C
Team
until
25
June
2015.
Members
of
10
May
2012
the
W3C
Advisory
Committee
will
find
the
appropriate
review
form
for
this
document
by
consulting
their
list
of
current
WBS
questionnaires
.
Comments on the document should be sent to the Working Group's public mailing list public-geolocation@w3.org ( subscribe , archives ). See W3C mailing list and archive usage guidelines .
The entrance criteria to enter the Proposed Recommendation stage was to have (1) a minimum of two independent and interoperable user agents that implement each feature of the Geolocation API and pass the User Agent Tests and (2) a minimum of two Websites that pass the Website Tests . During the Candidate Recommendation period, the group generated the Implementation Report which includes the information on known implementations. The group has confirmed 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 pass the Website Tests. See the Implementation Report for the details of the results.
This document has been produced by the W3C Geolocation Working Group , following the procedures set out for the W3C Process , with the intention of advancing it along the W3C Recommendation track.
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 .
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.
[NoInterfaceObject] interface {partial interface Navigator { readonly attribute Geolocation geolocation; };Navigator implements NavigatorGeolocation;
[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
should
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
should
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
.
[NoInterfaceObject] interface { attribute boolean <a href="#high-accuracy">enableHighAccuracy; attribute long ; attribute long ;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.
If
the
PositionOptions
parameter
to
getCurrentPosition
or
watchPosition
is
omitted,
the
default
value
used
for
the
enableHighAccuracy
attribute
is
false.
The
same
default
value
is
used
in
ECMAScript
when
the
enableHighAccuracy
property
is
omitted.
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.
If
the
PositionOptions
parameter
to
getCurrentPosition
or
watchPosition
is
omitted,
the
default
value
used
for
the
timeout
attribute
is
Infinity.
If
a
negative
value
is
supplied,
the
timeout
value
is
considered
to
be
0.
The
same
default
value
is
used
in
ECMAScript
when
the
timeout
property
is
omitted.
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