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 most recently formally published revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
If you wish to make comments regarding this document, please send them to public-geolocation@w3.org (subscribe, archives). All feedback is welcome.
Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing list and take part in the discussions.
No working group is yet responsible for this specification. This is just an informal proposal at this time.
[If you keep the <!--comment--> the table of contents will be included here automatically.]
This section is non-normative.
The Geolocation API defines a high-level interface to location information associated with the hosting device, such as latitude and longitude or a civic address (e.g., street address). 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, but could also include manually entered location information.
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 extract illustrates how to obtain basic location information:
Example of a "one-shot" position request.
function showMap(position) {
// Show a map centered at (position.latitude, position.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.latitude, position.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.latitude, position.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 immediately 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:Infinite, timeout:0});
function successCallback(position) {
// By setting the 'maximumAge' to Infinite, 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.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 APIs for retrieving geographic position information associated with a hosting device. Geodetic position information is provided in terms of World Geodetic System coordinates [WGS84]. Civic address information is provided in the format specified by RFC 5139 [RFC5139].
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 term origin is defined in the HTML 5 specification. [HTML5]
A location recipient is an entity that receives location via this API. Scripts on web pages that access this API are location recipients, as are third-party UA plugins or extensions that use this API to access location information. Each location recipient is identified by a URI, either the location of a web page or the origin of a plugin.
A location provider is an entity that provides location information that is exposed to location recipients (such as web pages and scripts) through this API. This may be a UA component, a function of the underlying host system, or a remote server accessed by the UA.
Privacy rules are policies that govern the use of location information. These rules grant access to a specific form of location to a specific set of recipients. The two principal sources of privacy rules are (1) users of a UA and (2) providers of location.
The API defined in this specification can be used by scripts to retrieve the geographic location of a hosting device. In most cases, disclosing the location of a device also discloses the location of its user. The disclosure and conveyance of this information on the Web raises unique privacy concerns, as location information can reveal intimate details about a user's whereabouts, indicate the user's presence at sensitive locations, and can be of particular interest to corporations, government authorities, and criminal elements.
The API defined in this specification defines a set of user-controlled privacy rules for User Agents to convey to scripts together with location information. While the API does not guarantee that scripts will adhere to these privacy rules, the critical value of binding such rules to location information is that no recipient of the location information can disavow knowledge of users' preferences for how their location may be used. By creating a structure to convey the user's preferences along with location information, the likelihood that those preferences will be honored necessarily increases, as does the ability of civil laws to enforce those preferences.
The structure and semantics of the privacy rules defined in this API are based on concepts developed by the IETF's Geographic Location/Privacy (GEOPRIV) Working Group and standardized in RFC 3693 [RFC3693] and RFC 4119 [RFC4119]. Inclusion of the rules in this API helps to both protect privacy and ensure compatability between IETF and W3C standards.
The existence of the privacy rules in this API has specific implications for both scripts that obtain location information from conforming User Agents and conforming User Agents themselves. These implications are discussed below.
A web page or script that uses this API accepts from the UA location objects that contain privacy rules. In this role, the script acts as a Location Recipient in the model of RFC 3693 [RFC3693]. This role requires a script to obey the privacy rules included in location objects it receives.
This specification cannot mandate any particular scripting behavior, as it simply provides an interface that scripts can use to obtain location information. However, the location recipients that leverage this API are central actors in protecting the privacy of users whose location information is conveyed by User Agents. Thus, this section describes the desired location recipient behaviors that the user can indicate with privacy rules in the API.
Location recipients will always receive, at minimum, two user-controlled privacy rule attributes together with enclosed location information: retransmissionAllowed and retentionExpires. In many cases, these two attributes can be sufficient to describe the user’s privacy preferences to the location recipient. User Agents may also provide two other privacy-related attributes, rulesetReference and noteWell, that location recipients may additionally use in conforming to the user’s privacy preferences. These four rules correspond to the sub-elements of the <usage-rules> element in RFC 4119 [RFC4119].
Note that location recipients can fully comply with even the most restrictive privacy rules simply by (a) not retransmitting location information to any third party, and (b) not retaining location information. Thus, for a location recipient that simply provides a one-time response to the user based on his or her location, the location recipient can promptly provide the requested information and then discard the location information. Any location recipients taking this approach (i.e., location recipients that perform no retention and no redistribution) will fully comply with all rules expressible under this API.
The retransmissionAllowed attribute indicates the user’s preference about whether his or her location information may be transmitted outside the location recipient's origin domain. When the value of this attribute is false, this indicates the user’s desire to forbid the location recipient from sharing his or her location information with other parties. A location recipient that receives location information bound by a retransmissionAllowed attribute set to false must not distribute the location information to any party that resides outside of its origin domain.
When the value of this attribute is true, this indicates the user’s permission for the location recipient to distribute the enclosed location information (barring an existing out-of-band agreement or obligation to the contrary).
The default value of this attribute is false.
The retentionExpires attribute indicates the user’s preference about how long the location recipient may retain his or her location information. The rule specifies an absolute date at which time the user desires that the location recipient no longer possess the enclosed location information. A location recipient that receives location information bound by a retentionExpires attribute set to a specified absolute date must not retain the location information beyond that date.
The default value of this attribute is 24 hours after the timestamp attribute of the location object containing the rule element.
The rulesetReference attribute contains a URI that indicates where a fuller rule set of policies related to the enclosed location information can be found. Constraints around access to rulesetReference URIs are described in RFC 4119 [RFC4119] and the format for expressing rules residing at a rulesetReference is specified in RFC 4745 [RFC4745] and [GEOLOC-POLICY]. Rules referenced by rulesetReference URIs consist of additional permissions that may override the user preferences expressed by the retransmissionAllowed and retentionExpires attributes.
A location recipient that receives a non-null rulesetReference may attempt to access the URI in order to apply the rules in the set to the accompanying location information. If the location recipient does not access the URI, then it must adhere to the retransmissionAllowed and retentionExpires attributes attached to the location.
As the rulesetReference is optional, it may be null. This is also the default value for this attribute.
The noteWell attribute contains a human-readable statement of other privacy preferences applicable to the location information. This human-readable statement is intended to summarize the privacy rules in the event that the location information is viewed in plain text or is otherwise human-accessible, and it is not intended to supplement, modify, or supercede the machine-readable rules. A location recipient should not modify its behavior based on the value of the noteWell attribute.
As the noteWell is optional, it may be null. This is also the default value for this attribute.
A UA that implements this API accepts location information from location providers and passes it to location recipients (such as web pages and scripts), subject to privacy rules set by the user. In this role, the UA acts as a Location Server in the model of RFC 3693 [RFC3693]. This role entails two key requirements:
rules object within the Position object provided through this API, as determined by the privacy rules.
A UA may receive privacy rules from two sources: from users directly and as transmitted by location providers. Users can directly specify rules either through static preferences or through dynamic, per-transaction interactions. For example, when a location recipient requests location, the UA might create a dialogue asking the user to set per-domain rules for the requesting domain. The same UA might also allow the user to set rules that apply to all domains.
A location provider that delivers a Geopriv object to a UA delivers privacy rules as part of that object. These rules are the default rules to be returned to location recipients (in the rules attribute of a Position object), unless they are modified by user-provided rules.
In order to maintain the privacy of a user's location information, a UA must maintain a set of privacy rules that determine when it can grant access to location. The privacy rules maintained by the UA are encoded in the policy language defined in RFC 4745 [RFC4745] and [GEOLOC-POLICY]. Rather than requiring implementation of the full rules language, this document requires UAs to implement a limited subset described below.
At the top level, the UA must have a rule browser-retransmission-allowed that specifies whether this API is enabled. The default value of this attribute must be false, in order to prevent the unintentional disclosure of the user's location. This rule acts as a top-level on/off switch controlling access to location information from the UA.
In addition to this top-level switch, the UA must maintain a database of privacy rules that grant location recipients access to location information. Each rule has a "condition" that specifies which recipients are granted access and a "transformation" that specifies how to construct the location object to be returned. By default, this rule set must be empty, indicating that no sites are permitted access.
The UA must allow users to designate allowed recipients based on three conditions:
The UA must enable the user to grant any of these permissions on a global level, on a per-domain basis, and on a per-URI basis. This constraint corresponds to the identity element of the rules language.
The UA must allow users to grant permissions according to the time at which the location is delivered (e.g., within a specified window of time). This constraint corresponds to the validity element of the rules language.
The UA must allow the user to specify whether the user is in a particular named state or "sphere." For example, a browser might set rules with an ephemeral "sphere" of applicability in order to set special permissions for a session. This constraint corresponds to the sphere element of the rules language.
To specify what location objects should be returned, a UA must implement four types of transformation, and should implement two others. These rules correspond to the rule elements of [GEOLOC-POLICY], where their normative meanings are defined. The descriptions provided here are non-normative, provided for readability.
provide-geo: Grant access to geodetic location information with specified granularity. This transformation contains a numeric value that specifies the maximum precision of the returned location.provide-civic: Grant access to civic location information. This transformation contains a token that specifies a set of civic fields that may be returned.set-retransmission-allowed: Set the value of the rules.retransmissionAllowed attribute in the returned location object. This transformation contains a boolean value.set-retention-expires: Set the value of the rules.retentionExpires attribute in the returned location object. This transformation contains an absolute date.set-ruleset-reference (optional): Set the value of the rules.rulesetReference attribute in the returned location object. This tranformation contains a URI string.set-note-well (optional): Set the value of the rules.noteWell attribute in the returned location object. This transformation contains a note well string.When a location recipient calls either getCurrentPosition() or watchPosition() and a location provider delivers a Position object to the UA, the User Agent must take the following steps to apply privacy rules before invoking the associated successCallback argument. The inputs to this process are the URI of the requesting page, the provided Position object, and a string identifying the current state of the the user (the "sphere"). The result of this process is either a call to successCallback or nothing (an "abort"); in the latter case, the UA may invoke the associated errorCallback.
browser-retransmission-allowed rule is set to false, then abort. This check could optimally be done prior to acquiring the Position object.provide-geo: The permitted uncertainty radius is the minimum among the selected rules.provide-civic: The permitted granularity is the most specific granularity among the selected rules.set-retransmission-allowed: The permitted value is true if any rule is true (logical OR).set-retention-expires: The permitted value is the temporally last among the selected rules set-ruleset-reference and set-note-well are unspecified. At the end of this step, the UA has a single net transformation to be applied to the provided Position object.
provide-geo or provide-civic rule, then abort.pos:
pos.geodetic is non-null and no provide-geo transformation is present, set pos.geodetic to null. pos.geodetic is non-null and a provide-geo transformation is present, change pos.geodetic to a location with the uncertainty radius specified. pos.civic is non-null and no provide-civic transformation is present, set pos.geodetic to null. pos.civic is non-null and a provide-civic transformation is present, set to null all pos.civic attributes not in the allowed set. pos.rules is null, then set it to a new PrivacyRules object with default values.set-*) are present, then set the attributes of pos.rules with these values. If pos.rules is non-null, then the UA may prompt the user before overwriting these values (or use the results of previous prompts).successCallback with the transformed Position objectSome UAs may cache Position objects returned by location providers. Position objects in this cache must be considered as raw, unauthorized Position objects -- the UA must go through the above authorization process before providing them to a location recipient.
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]
The Geolocation object can
be 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.
[NoInterfaceObject]
interface NavigatorGeolocation {
readonly attribute Geolocation geolocation;
};
interface Geolocation {
void getCurrentPosition(in PositionCallback successCallback);
void getCurrentPosition(in PositionCallback successCallback, in PositionErrorCallback errorCallback);
void getCurrentPosition(in PositionCallback successCallback, in PositionErrorCallback errorCallback, in PositionOptions options);
int watchPosition(in PositionCallback successCallback);
int watchPosition(in PositionCallback successCallback, in PositionErrorCallback errorCallback);
int watchPosition(in PositionCallback successCallback, in PositionErrorCallback errorCallback, in PositionOptions options);
void clearWatch(in int watchId);
};
interface PositionCallback {
void handleEvent(in Position position);
};
interface PositionErrorCallback {
void handleEvent(in PositionError error);
};
The getCurrentPosition()
takes one, two or three arguments. When called, it must immediately
return and then asynchronously acquire a new Position object.
If successful, this method must invoke its associated
successCallback argument with a Position object as an argument. If the
attempt fails, and the method was invoked with a non-null
errorCallback argument, this method must invoke the
errorCallback with a PositionError object as an
argument.
The watchPosition()
takes one, two or three arguments. When called, it must immediately
return and then asynchronously start a watch process defined
as the following set of steps:
Position object.
If successful, invoke the associated successCallback with a Position object as an argument.
If the attempt fails, and the method was invoked with a non-null
errorCallback argument, this method must invoke the
errorCallback with a PositionError object as an
argument.
Position
object every time the implementation determines that the position
of the hosting device has changed.
This method returns an integer value that uniquely identifies the
watch process. When the clearWatch()
method is called with this identifier, the watch process must stop
acquiring any new position fixes and must cease invoking any callbacks.
The getCurrentPosition() and
watchPosition() methods
accept PositionOptions objects as
their third argument.
PositionOptions
objects are regular ECMAScript objects that have the following properties:
[NoInterfaceObject]
interface PositionOptions {
attribute boolean enableHighAccuracy;
attribute long timeout;
attribute long maximumAge;
};
The enableHighAccuracy, timeout
and maximumAge attributes are all optional.
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.
enableHighAccuracy is trying to solve.
The timeout attribute denotes
the maximum length of time (expressed in milliseconds) that is
allowed to pass from the 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.
In case of a getCurrentPosition() call, the
errorCallback would be invoked exactly once.
In case of a watchPosition(), the
errorCallback could be invoked repeatedly: the first
timeout is relative to the moment watchPosition() was
called, while 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 not specified or set to 0,
the implementation must immediately attempt to acquire a new
position object. Setting the maximumAge to Infinite
will force the implementation to return a cached position regardless
of its age. If an implementation does not have available a cached
position 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 callbacks provided in calls to the Geolocation interface are provided with location information via Position objects. This API supports two types of location: Geodetic location and civic location. Geodetic location describes location mathematically, in terms of the WGS84 coordinate reference system. Civic location describes location in terms of addresses and other related constructs. In addition, a Position object comes with privacy rules that describe how the application should handle the location.
interface Position {
readonly attribute GeodeticPosition geodetic;
readonly attribute CivicPosition civic;
readonly attribute PrivacyRules rules;
readonly attribute DOMTimeStamp timestamp;
};
interface GeodeticPosition {
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
};
interface CivicPosition {
readonly attribute DOMString country;
readonly attribute DOMString A1;
readonly attribute DOMString A2;
readonly attribute DOMString A3;
readonly attribute DOMString A4;
readonly attribute DOMString A5;
readonly attribute DOMString A6;
readonly attribute DOMString PRM;
readonly attribute DOMString PRD;
readonly attribute DOMString RD;
readonly attribute DOMString STS;
readonly attribute DOMString POD;
readonly attribute DOMString POM;
readonly attribute DOMString RDSEC;
readonly attribute DOMString RDBR;
readonly attribute DOMString RDSUBBR;
readonly attribute DOMString HNO;
readonly attribute DOMString HNS;
readonly attribute DOMString LMK;
readonly attribute DOMString LOC;
readonly attribute DOMString FLR;
readonly attribute DOMString NAM;
readonly attribute DOMString PC;
readonly attribute DOMString BLD;
readonly attribute DOMString UNIT;
readonly attribute DOMString ROOM;
readonly attribute DOMString SEAT;
readonly attribute DOMString PLC;
readonly attribute DOMString PCN;
readonly attribute DOMString POBOX;
readonly attribute DOMString ADDCODE;
};
interface PrivacyRules {
readonly attribute boolean retransmissionAllowed;
readonly attribute DOMTimeStamp retentionExpires;
readonly attribute DOMString rulesetReference;
readonly attribute DOMString noteWell;
};
A Position object can contain location information in on or more location constructs. The geodetic attribute provides location in geodetic form and the civic attribute provides location in civic form. Either of these fields MAY be null if location is not available in the given form, but one of these fields MUST be populated (not null) in any given Position object.
The rules attribute provides a set of privacy rules that instruct the web site in how it should handle this location information in order to preserve the user's privacy. (See the privacy considerations section.)
The timestamp attribute
represents the time when the location was acquired and is
represented as a DOMTimeStamp [DOMTIMESTAMP].
The reference system used for the positioning attributes of this interface is the World Geodetic System [WGS84].
The latitude and longitude
attributes are specified in 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 altitudeAccuracy attribute
is specified in meters. If the implementation cannot provide
altitude information, the value of this attribute must be null.
The accuracy and altitudeAccuracy
values returned by an implementation should correspond to a 95%
confidence level.
The heading attribute
denotes the direction of the hosting device and is specified in
degrees counting clockwise relative to the true north. If the
implementation cannot provide heading information, the value of this
attribute must be null.
The speed attribute
denotes the current ground speed of the hosting device and is
specified in meters per second. If the implementation cannot
provide speed information, the value of this attribute must be
null.
A Geodetic position object contains many fields corresponding to components of a Civic Address described in RFC 5139 [RFC5139]. These fields are to be interpreted as defined in that document.
The privacy rules structure defines four types of rules that indicate the user's preferences for how web sites handle location information. These rules correspond to the sub-elements of the <usage-rules> element in RFC 4119 [RFC4119], with additional considerations as described in the Privacy Considerations above. We review their meanings briefly here.
The retransmissionAllowed attribute indicates whether the recipient should transmit location to other entities. If this attribute is set to true, then the recipient may transmit location, otherwise, it must not.
The retentionExpires attribute describes how long the recipient should retain this location object, given as a DOMTimeStamp [DOMTIMESTAMP] for the time after which the location must be deleted.
The rulesetReference attribute contains an optional URI pointing to an external document containing more expressive privacy rules.
The noteWell attribute provides an optional human-readable statement of other privacy preferences applicable to the location information.
interface PositionError {
const unsigned short UNKNOWN_ERROR = 0;
const unsigned short PERMISSION_DENIED = 1;
const unsigned short POSITION_UNAVAILABLE = 2;
const unsigned short TIMEOUT = 3;
readonly unsigned short code;
readonly DOMString message;
};
The code attribute must return
the appropriate code from the following list:
UNKNOWN_ERROR (numeric value 0)PERMISSION_DENIED (numeric value 1)POSITION_UNAVAILABLE (numeric value 2)TIMEOUT (numeric value 3)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.
Issue note: This section will get moved to a separate document
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. The user's privacy rules might deny retransmission and limit retention to the length of the user's stay in the city since it is not necessary for the Web application to share the user's location with other parties or retain the user's location after the points of interest have been provided.
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. The users in these cases might set their privacy rules to allow retransmission and indefinite retention, since they want the location data tags to be accessible to anyone over time. Alternatively, if the user agent supports more robust privacy rules pursuant to [GEOLOC-POLICY], the friends may wish to define more privacy rules that would allow (for example) family members to view precise location information and all others to view more general location information (such as country-level information).
A user is accessing an online service in order to arrange a parcel delivery and she needs to fill in a long form which includes special fields for her home address. To save the user's time, the application tries to pre-fill the address part of the form by using the Geolocation API to acquire the user's current location as a (latitude, longitude) pair as well as an address object. If an implementing User Agent cannot provide the address object, the application uses a third-party reverse geocoding service to translate the coordinates into a street address. The user's privacy rules might indicate that retransmission is prohibited but retention is not limited, because the service need not share her location information but may need to retain a record of the shipment for a significant duration.
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. The user's privacy rules might be set to deny retransmission and limit retention to 24 hours since the mapping application need not share her location nor retain it beyond the time it takes to locate her on the map.
Following from use case 4, 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. The privacy rule settings from use case 4 may also be applied here. Alternatively, if the user wants to be able to review previous routes at a later date, she may set her retention rule to be longer than 24 hours.
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. The user might set her retransmission rule to deny retransmission globally, but allow the tour guide application to retransmit her location so that tourist attractions can offer her coupons when she is nearby. The user's retention rule might be set to a week or less to limit the tour guide application and other applications that receive her location from creating a profile of her whereabouts.
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. The user's privacy rules might be set to deny retransmission and limit retention to 24 hours since the widget provides only current information based on location.
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 and using only certain parts from the Address object. 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. The user's privacy rules might be set to prohibit retransmission (so that the social network cannot share location information with advertisers, for example) and allow indefinite retention since the location tags are meant to last over time.
Alec Berntson, Steve Block, Greg Bolsinga, Aaron Boodman, Dave Burke, Chris Butler, Shyam Habarakada, Ian Hickson, Brad Lassey, Daniel Park, Stuart Parmenter, Olli Pettay, Chris Prince, Arun Ranganathan, Aza Raskin, Martin Thomson, Doug Turner, Mohamed Zergaoui