This
specification
defines
an
API
that
provides
scripted
access
to
geographical
location
information
associated
with
the
hosting
device.
Status
of
This
Document
This
is
a
preview
Do
not
attempt
to
implement
this
version
of
the
specification.
Do
not
reference
this
version
as
authoritative
in
any
way.
Instead,
see
https://w3c.github.io/geolocation-api/
for
the
Editor's
draft.
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/.
The
Devices
and
Sensors
Working
Group
will
maintain
errata
and
new
editions,
as
necessary,
for
the
Geolocation
API.
GitHub
Issues
are
preferred
for
discussion
of
this
specification.
Publication
as
an
Editor's
Draft
does
not
imply
endorsement
by
the
W3C
Membership.
This
is
a
draft
document
and
may
be
updated,
replaced
or
obsoleted
by
other
documents
at
any
time.
It
is
inappropriate
to
cite
this
document
as
other
than
work
in
progress.
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
],
the
Gears
Geolocation
API,
and
LocationAware.org
.
The
following
code
extracts
illustrate
how
to
obtain
basic
location
information:
Example
1
:
Example
of
a
"one-shot"
position
request
functionshowMap(position) {
// Show a map centered at (position.coords.latitude, position.coords.longitude).
}
// One-shot position request.
navigator.geolocation.getCurrentPosition(showMap);
Example
2
:
Example
of
requesting
repeated
position
updates
functionscrollMap(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);
functionbuttonClickHandler() {
// Cancel the updates when the user clicks a button.
navigator.geolocation.clearWatch(watchId);
}
Example
3
:
Example
of
requesting
repeated
position
updates
and
handling
errors
functionscrollMap(position) {
// Scrolls the map so that it is centered at// (position.coords.latitude, position.coords.longitude).
}
functionhandleError(error) {
// Update a div element with error.message.
}
// Request repeated updates.var watchId = navigator.geolocation.watchPosition(scrollMap, handleError);
functionbuttonClickHandler() {
// Cancel the updates when the user clicks a button.
navigator.geolocation.clearWatch(watchId);
}
Example
4
:
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,
});
functionsuccessCallback(position) {
// By using the 'maximumAge' option above, the position// object is guaranteed to be at most 10 minutes old.
}
functionerrorCallback(error) {
// Update a div element with error.message.
}
Example
5
:
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,
});
functionsuccessCallback(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.
}
functionerrorCallback(error) {
switch (error.code) {
case GeolocationPositionError.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.
}
}
functiondoFallback() {
// No fresh enough cached position available.// Fallback to a default position.
}
Example
6
:
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
});
functionsuccessCallback(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.
}
}
functionerrorCallback(error) {
switch(error.code) {
case GeolocationPositionError.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.
};
}
functiondoFallback() {
// No cached position available at all.// Fallback to a default position.
}
2.
Scope
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
a
new
scheme
for
building
URLs
that
identify
geographic
locations.
3.
Security
and
privacy
considerations
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.
3.1
Privacy
considerations
for
implementers
of
the
Geolocation
API
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
URL.
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
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.
3.2
Privacy
considerations
for
recipients
of
location
information
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.
3.3
Additional
implementation
considerations
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
attribute
gives
access
to
location
information
associated
with
the
hosting
device.
4.2
Geolocation
interface
The
Geolocation
interface
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
GeolocationPosition
object,
and
populating
that
object
with
appropriate
data
accordingly.
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
with
a
new
GeolocationPosition
object,
reflecting
the
current
location
of
the
device.
If
the
attempt
fails,
the
errorCallback
MUST
be
invoked
with
a
new
GeolocationPositionError
object,
reflecting
the
reason
for
the
failure.
The
implementation
of
the
getCurrentPosition
()
method
MUST
execute
the
following
set
of
steps:
If
a
cached
GeolocationPosition
object,
whose
age
is
no
greater
than
the
value
of
the
maximumAge
variable,
is
available,
invoke
the
successCallback
with
the
cached
GeolocationPosition
object
as
a
parameter
and
exit
this
set
of
steps.
Start
a
location
acquisition
operation
(e.g.
by
invoking
a
platform-specific
API),
possibly
taking
into
account
the
value
of
the
enableHighAccuracy
variable.
Start
a
timer
that
will
fire
after
the
number
of
milliseconds
denoted
by
the
value
of
the
timeout
variable.
When
the
timer
fires,
cancel
any
ongoing
location
acquisition
operations
associated
with
this
instance
of
the
steps,
invoke
the
errorCallback
(if
present)
with
a
new
GeolocationPositionError
object
whose
code
attribute
is
set
to
GeolocationPositionError
.
TIMEOUT
,
and
exit
this
set
of
steps.
If
the
operation
completes
successfully
before
the
timeout
expires,
cancel
the
pending
timer,
invoke
the
successCallback
with
a
new
GeolocationPosition
object
that
reflects
the
result
of
the
acquisition
operation
and
exit
this
set
of
steps.
The
watchPosition()
method
takes
one,
two
or
three
arguments.
When
called,
immediately
return
a
long
value
that
uniquely
identifies
a
watch
process
and
continue
asynchronously.
Otherwise,
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
with
a
new
GeolocationPosition
object,
reflecting
the
current
location
of
the
device.
If
the
attempt
fails,
the
errorCallback
MUST
be
invoked
with
a
new
GeolocationPositionError
object,
reflecting
the
reason
for
the
failure.
The
watch
process
then
MUST
continue
to
monitor
the
position
of
the
device
and
invoke
the
appropriate
callback
every
time
this
position
changes.
The
watch
process
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:
If
a
cached
GeolocationPosition
object,
whose
age
is
no
greater
than
the
value
of
the
maximumAge
variable,
is
available,
invoke
the
successCallback
with
the
cached
GeolocationPosition
object
as
a
parameter.
Register
to
receive
system
events
that
indicate
that
the
position
of
the
device
MAY
have
changed
(e.g.
by
listening
or
polling
for
changes
in
WiFi
or
cellular
signals).
Start
a
location
acquisition
operation
(e.g.
by
invoking
a
platform-specific
API),
possibly
taking
into
account
the
value
of
the
enableHighAccuracy
variable
(see
the
definition
of
enableHighAccuracy
for
details).
If
the
location
acquisition
operation
successfully
yields
a
new
position
before
the
timeout
expires,
perform
the
following
two
steps:
Cancel
the
pending
timer.
Note
that
the
timer
MUST
be
restarted
once
this
algorithm
jumps
back
to
the
beginning
of
the
acquisition
steps.
If
the
new
position
differs
significantly
from
the
previous
position
,
invoke
the
successCallback
with
a
new
GeolocationPosition
object
that
reflects
the
result
of
the
acquisition
operation.
This
step
MAY
be
subject
to
callback
rate
limitation
.
Wait
for
a
system
event
to
be
received
.
When
such
an
event
is
received
jump
to
the
acquisition
steps
above.
Note
If
the
new
position
differs
significantly
from
the
previous
position
in
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
4.2.2
and
4.3,
implementations
MAY
impose
a
rate
limit
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
set
to
GeolocationPositionError
.
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.
4.2.3
clearWatch()
method
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.
4.2.4
PositionCallBack
callback
The
PositionCallBack
callback
is
invoked
when
a
GeolocationPosition
object
is
available,
resulting
from
a
cached
object
or
the
acquisition
operation.
The
PositionCallBack
callback
gets
set
using
the
successCallback
parameter.
4.2.5
PositionErrorCallBack
callback
The
PositionErrorCallBack
callback
is
invoked
when
a
GeolocationPosition
object
is
not
available,
resulting
from
a
timeout,
a
permission
denied,
or
an
unability
to
determine
the
position
of
the
device.
The
PositionErrorCallBack
callback
gets
set
using
the
errorCallback
parameter.
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.
4.3.2
timeout
member
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
GeolocationPosition
before
the
given
timeout
elapses,
and
no
other
errors
have
occurred
in
this
interval,
then
the
corresponding
errorCallback
MUST
be
invoked
with
a
GeolocationPositionError
object
whose
code
attribute
is
set
to
GeolocationPositionError
.
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
GeolocationPosition
object
MUST
be
acquired.
4.3.3
maximumAge
member
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
GeolocationPosition
object.
In
case
of
a
watchPosition
()
,
the
maximumAge
refers
to
the
first
GeolocationPosition
object
returned
by
the
implementation.
The
GeolocationPosition
interface
is
the
container
for
the
geolocation
information
returned
by
this
API.
This
version
of
the
specification
allows
one
attribute
of
type
GeolocationCoordinates
and
a
timestamp
.
Future
versions
of
the
API
MAY
allow
additional
attributes
that
provide
other
information
about
this
position
(e.g.
street
addresses).
4.4.1
coords
attribute
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
geographic
coordinate
reference
system
used
by
the
attributes
in
this
interface
is
the
World
Geodetic
System
(2d)
[
WGS84
].
No
other
reference
system
is
supported.
4.5.1
latitude
attribute
The
latitude
and
longitude
attributes
are
geographic
coordinates
specified
in
decimal
degrees.
4.5.2
altitude
attribute
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.
4.5.3
accuracy
attribute
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.
4.5.4
altitudeAccuracy
attribute
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.
4.5.5
heading
attribute
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.
4.5.6
speed
attribute
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.
The
code
attribute
MUST
return
the
appropriate
code
from
the
following
list:
PERMISSION_DENIED
(numeric
value
1)
The
location
acquisition
process
failed
because
the
document
does
not
have
permission
to
use
the
Geolocation
API.
POSITION_UNAVAILABLE
(numeric
value
2)
The
position
of
the
device
could
not
be
determined.
For
instance,
one
or
more
of
the
location
providers
used
in
the
location
acquisition
process
reported
an
internal
error
that
caused
the
process
to
fail
entirely.
TIMEOUT
(numeric
value
3)
The
length
of
time
specified
by
the
timeout
property
has
elapsed
before
the
implementation
could
successfully
acquire
a
new
GeolocationPosition
object.
4.6.2
message
attribute
The
message
attribute
is
a
developer-friendly
textual
description
of
the
code
attribute.
Note
The
purpose
of
the
message
attribute
is
to
assist
with
debugging
and
it's
not
intended
to
be
shown
to
end
users.
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.
6.1.2
Annotating
content
with
location
information
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.
6.1.3
Show
the
user's
position
on
a
map
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.
6.1.4
Turn-by-turn
route
navigation
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.
6.1.5
Alerts
when
points
of
interest
are
in
the
user's
vicinity
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.
6.1.6
Up-to-date
local
information
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.
6.1.7
Location-tagged
status
updates
in
social
networking
applications
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.
6.2
Requirements
This
section
is
non-normative.
The
Geolocation
API
MUST
needs
to
provide
location
data
in
terms
of
a
pair
of
latitude
and
longitude
coordinates.
The
Geolocation
API
MUST
needs
to
provide
information
about
the
accuracy
of
the
retrieved
location
data.
The
Geolocation
API
MUST
needs
to
support
"one-shot"
position
updates.
The
Geolocation
API
MUST
needs
to
allow
an
application
to
register
to
receive
updates
when
the
position
of
the
hosting
device
changes.
The
Geolocation
API
MUST
needs
to
allow
an
application
to
request
a
cached
position
whose
age
is
no
greater
than
a
specified
value.
The
Geolocation
API
MUST
needs
to
provide
a
way
for
the
application
to
receive
updates
about
errors
that
MAY
have
occurred
while
obtaining
a
location
fix.
The
Geolocation
API
MUST
needs
to
allow
an
application
to
specify
a
desired
accuracy
level
of
the
location
information.
The
Geolocation
API
MUST
needs
to
be
agnostic
to
the
underlying
sources
of
location
information.
7.
Conformance
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
,
MUST
NOT
,
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.
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.
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,
and
Mohamed
Zergaoui.