Abstract

This specification defines an API that provides scripted access to
geographical location information associated with the hosting device.

Status of This Document

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

Publication as a Working 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.

1 Conformance requirements

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]

2 Introduction

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. When providing the
location of the device and where practically possible, the API should provide
the location of the device's center of mass. The velocity reported by the API
should also be that of the center of mass.

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:

// 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 aynchronously 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.
}

3 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] or in terms
of a civic address, or both.

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.

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

4.1 Privacy
considerations for implementors 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 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.

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

4.3
Additional implementation considerations

This section is non-normative.

Further to the requirements listed in the previous section, implementors
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, implementors are advised to enable user
awareness of location sharing, and to provide easy access to interfaces
that enable revocation of permissions.

5 API Description

5.1 Geolocation
interface

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.

Objects implementing the Navigator interface (e.g. the
window.navigator object) must also implement the NavigatorGeolocation interface [NAVIGATOR]. An instance of NavigatorGeolocation would be then obtained by
using binding-specific casting methods on an instance of
Navigator.

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 execute the following set of steps:

Run the following pre-processing steps:

If successCallback is the null value,
then throw a TypeError. This matches a failed type conversion in WebIDL.
See step 5 in section 4.1.15 in [WEBIDL].

If a PositionOptions parameter was present,
and its maximumAge attribute was defined to a
non-negative value, assign this value to an internal
maximumAge variable. If maximumAge was defined
to a negative value or was not specified, set the internal maximumAge
variable to 0.

If a PositionOptions parameter was present,
and its timeout attribute was defined to a
non-negative value, assign this value to an internal timeout
variable. If timeout was defined to a negative value,
set the internal timeout variable to 0. If
timeout was not specified, set the internal timeout
variable to Infinity.

If a PositionOptions parameter was present,
and its enableHighAccuracy attribute was
defined, assign this value to an internal enableHighAccuracy
variable. Otherwise, set the internal enableHighAccuracy
variable to false.

If a PositionOptions parameter was present, and its
requireCoords attribute was defined, assign this value to
an internal requireCoords variable. Otherwise, set the internal
requireCoords variable to true.

If a PositionOptions parameter was present, and its
requestAddress attribute was defined, assign this value to
an internal requestAddress variable. Otherwise, set the internal
requestAddress variable to false.

If a cached Position object is available, whose age is no
greater than the value of the maximumAge variable, and which provides all
relevant attributes if the value of the requireCoords variable is
true, invoke the successCallback with the cached
Position object as a parameter and exit this set of steps.

If the value of the timeout variable is 0, invoke
the errorCallback (if present) with a
new PositionError object whose code
attribute is set to TIMEOUT and exit this set of steps.

Start a location acquisition operation (e.g. by invoking a
platform-specific API), possibly taking into account the values of the
enableHighAccuracy and requestAddress variables. See the definition of
enableHighAccuracy and
requestAddress for details.

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 PositionError object
whose code attribute is set to 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 Position object that reflects the result of the
acquisition operation and exit this set of steps. Note that if the value of
the requireCoords variable is true, the success criteria
includes providing non-null values for all relevant attributes of the
Position object.

If the operation fails before the timeout expires, cancel the
pending timer and invoke the 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 execute the
following set of steps:

Run the following pre-processing steps:

If successCallback is the null value,
then throw a TypeError. This matches a failed type conversion in WebIDL.
See step 5 in section 4.1.15 in [WEBIDL].

If a PositionOptions parameter was present,
and its maximumAge attribute was defined to a
non-negative value, assign this value to an internal
maximumAge variable. If maximumAge was defined
to a negative value or was not specified, set the internal maximumAge
variable to 0.

If a PositionOptions parameter was present,
and its timeout attribute was defined to a
non-negative value, assign this value to an internal timeout
variable. If timeout was defined to a negative value,
set the internal timeout variable to 0. If
timeout was not specified, set the internal timeout
variable to Infinity.

If a PositionOptions parameter was present,
and its enableHighAccuracy attribute was
defined, assign this value to an internal enableHighAccuracy
variable. Otherwise, set the internal enableHighAccuracy
variable to false.

If a PositionOptions parameter was present, and its
requireCoords attribute was defined, assign this value to
an internal requireCoords variable. Otherwise, set the internal
requireCoords variable to true.

If a PositionOptions parameter was present, and its
requestAddress attribute was defined, assign this value to
an internal requestAddress variable. Otherwise, set the internal
requestAddress variable to false.

If a cached Position object is available, whose age is no
greater than the value of the maximumAge variable, and which provides all
relevant attributes if the value of the requireCoords variable is
true, invoke the successCallback with the cached
Position object as a parameter and exit this set of steps.

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 values of the
enableHighAccuracy and requestAddress variables. See the definition of
enableHighAccuracy and
requestAddress for details.

Run the following acquisition steps:

If the timer is not already running, start a timer that will fire after the number of
milliseconds denoted by the value of the timeout
variable. When the timer fires, invoke
the errorCallback (if present) with a
new PositionError object whose code
attribute is set to TIMEOUT and jump to step 6.

If the location acquisition operation completes successfully before
the timeout expires, perform the following two steps. Note that if the
value of the requireCoords variable is true, the success
criteria includes providing non-null values for all relevant attributes
of the Position object.

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 Position object that reflects the
result of the acquisition operation. This step may be
subject to callback rate limitation
(see below).

Else, if the location acquisition operation reports an
error before the timeout expires, invoke the 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).

Wait for a system event to be received. When such an event is
received jump to the acquisition steps above.

In step 5.2.2 of the watch process,
the successCallback is only invoked when a new position
is obtained and this position differs signifficantly from the
previously reported position. The definition of what consitutes 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.

When a user agent is to unload a document, it must abort any
watch processes created with navigator.geolocation.watchPosition() from
within that document. For example, similar steps are defined in HTML5[UNLOADING DOCUMENTS].

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.

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.

If the PositionOptions parameter
to getCurrentPosition or watchPosition is
omitted, the default value used for the maximumAge
attribute is 0. If a negative value is supplied,
the maximumAge value is considered to be 0. The same
default value is used in ECMAScript when the maximumAge
property is omitted.

The requireCoords attribute
instructs the user agent that if it is unable to provide values for the
Position.coords.latitude, Position.coords.longitude
and Position.coords.accuracy attributes, it must consider the
location acquisition process a failure and invoke the error callback. This
means that when requireCoords is set to true,
applications can guarantee that if the success callback is invoked,
Position.coords, Position.coords.latitude,
Position.coords.longitude and
Position.coords.accuracy are non-null.

If the PositionOptions parameter to
getCurrentPosition or watchPosition is omitted, the
default value used for the requireCoords attribute is
true. The same default value is used in ECMAScript when the
requireCoords property is omitted. This means that applications
written to use V1 of this specification will see no change in behavior when
run in a user agent supporting V2 of this spec.

The requestAddress attribute
provides a hint to the user agent that the application would like to receive a
civic address. The intended purpose of this attribute is to provide a means
for user agents to avoid the potentially expensive process of obtaining a
civic address when it is not required by the application. Note that a user
agent's failure to obtain a civic addres when requestAddress is
true must not imply that the overall location acquisition
process has failed.

If the PositionOptions parameter to
getCurrentPosition or watchPosition is omitted, the
default value used for the requestAddress attribute is
false. The same default value is used in ECMAScript when the
requestAddress property is omitted.

5.3 Position interface

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.

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
coords attribute is optional.

The address attribute contains a set
of properties that describe a location on the Earth's surface using a civic
address. The address attribute is optional.

The timestamp attribute represents
the time when the Position object was
acquired and is represented as a DOMTimeStamp [DOMTIMESTAMP].

Note that although both the coords and address
attributes are optional, user agents must consider a location acquisition
process that provides neither of these attributes to be a failure. In this
case, the success callback must not be invoked.

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. If the implementation cannot provide this
information, the value of the corresponding attribute must be null.

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 and is specified
in meters. If the implementation cannot provide accuracy information, or if
either the latitude or longitude attribute is null,
the value of this attribute must be null. Otherwise, the value of this
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 this attribute must be a non-negative real number.

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 this attribute must be
a non-negative real number.

The verticalSpeed attribute
denotes the magnitude of the vertical 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 this attribute must be
a non-negative real number.

Note that although all attributes of the Coordinates interface
are optional, user agents must never provide a object in
which all attributes of Postition.coords are null. Instead,
Position.coords itself must be null.

All of the Address attributes are optional. If an
implementation cannot provide a particular attribute, its value must
be null.

The country attribute is
specified using the two-letter [ISO
3166-1] code.

The region denotes the name
of a country subdivision (e.g. the state name in the US).

The county denotes the name
of a land area within the larger region.

The city reflects the name of
the city.

The street reflects the name
of the street.

The streetNumber
reflects the location's street number.

The premises denotes the
details of the premises, such as a building name, block of flats,
etc.

The postalCode reflects
the postal code of the location (e.g. the zip code in the US).

Note that although all attributes of the Address interface
are optional, user agents must never provide a object in
which all attributes of Postition.address are null. Instead,
Position.address itself must be null.

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

6 Use-Cases and Requirements

6.1 Use-Cases

6.1.1 Find points of
interest in the user's area

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.

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 neighbourhood 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.1.8
Automatic form filling.

A pizza-ordering Web page is using the Geolocation API v2 to help users
auto-fill the delivery address part of the ordering form.

6.2 Requirements

6.2.1 The Geolocation API
must provide a way for an application to receive location data in terms
of a pair of latitude and longitude coordinates.

6.2.2 The Geolocation API
must provide a way for an application to receive information about the
accuracy of the retrieved location data.

6.2.3 The Geolocation API
must support "one-shot" position updates.

6.2.4 The Geolocation API
must allow an application to register to receive updates when the position
of the hosting device changes.

6.2.5 The Geolocation API
must allow an application to request a cached position whose age is no
greater than a specified value.

6.2.6 The Geolocation API must
provide a way for the application to receive updates about errors that may
have occurred while obtaining a location fix.

6.2.7 The Geolocation
API must allow an application to specify a desired accuracy level of the
location information.

6.2.8 The Geolocation
API must be agnostic to the underlying sources of location information.

6.2.9 The Geolocation
API must provide a way for an application to receive location data as a civic address.

6.2.10 The Geolocation
API must allow an application to specify the type of location information
that it wishes to receive.

6.2.11 The Geolocation
API must be backwards compatible with all previously published versions of this API.