index.html 68.4 KB

Raw Blame History Permalink

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">

<html lang=en>
 <head>
  <title>Geolocation API Specification Level 2</title>
  <meta content="text/html;charset=utf-8" http-equiv=Content-Type>

  <style type="text/css">
   dt, dfn { font-weight: bold; font-style: normal; }
   img.extra { float: right; }
   body ins, body del { display: block; }
   body * ins, body * del { display: inline; }
   pre, code { color: black; background: transparent; font-size: inherit; font-family: monospace; }
   pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
   pre em { font-weight: bolder; font-style: normal; }
   pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
   pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em; }
   table { border-collapse: collapse; border-style: hidden hidden none hidden; }
   table thead { border-bottom: solid; }
   table tbody th:first-child { border-left: solid; }
   table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
   ul.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
   ul.toc li ul { margin-bottom: 0.75em; }
   ul.toc li ul li ul { margin-bottom: 0.25em; }
   var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
   @media screen { code { color: rgb(255, 69, 0); background: transparent; } }
   code :link, code :visited { color: inherit; background: transparent; }
   .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 1em; padding-left: 1em; }
   .issue, .big-issue { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
   .issue > :first-child, .big-issue > :first-child { margin-top: 0; }
   p .big-issue { line-height: 3em; }
   .note { color: green; background: transparent; }
   .note { font-family: sans-serif; }
   p.note:before { content: 'Note: '; }
   .warning { color: red; background: transparent; }
   .warning:before { font-style: normal; }
   p.warning:before { content: '\26A0 Warning! '; }
   .note, .warning { font-weight: bolder; font-style: italic; padding: 0.5em 2em; }
   .copyright { margin: 0.25em 0; }
   img { max-width: 100%; }
   h4 + .element { margin-top: -2.5em; padding-top: 2em; }
   h4 + p + .element { margin-top: -5em; padding-top: 4em; }
   .element { background: #EEEEFF; color: black; margin: 0 0 1em -1em; padding: 0 1em 0.25em 0.75em; border-left: solid #9999FF 0.25em; }
   table.matrix, table.matrix td { border: none; text-align: right; }
   table.matrix { margin-left: 2em; }
  </style>
  <link href="http://www.w3.org/StyleSheets/TR/W3C-WD.css" rel=stylesheet
  type="text/css">

 <body>
  <div class=head> <!--begin-logo-->
   <p><a href="http://www.w3.org/"><img alt=W3C height=48
    src="http://www.w3.org/Icons/w3c_home" width=72></a> <!--end-logo-->

   <h1 id="title_heading">Geolocation API Specification Level 2</h1>

   <h2 class="no-num no-toc" id="draft_date">W3C Working Draft 1 December 2011</h2>

   <dl>
    <dt>This Version:</dt>
      <dd><a href="http://www.w3.org/TR/2011/WD-geolocation-API-v2-20111201/">http://www.w3.org/TR/2011/WD-geolocation-API-v2-20111201/</a></dd>

    <dt>Latest Published Version:</dt>

    <dd><a
     href="http://www.w3.org/TR/geolocation-API-v2/">http://www.w3.org/TR/geolocation-API-v2/</a></dd>

    <dt>Latest Editor's Draft:

    <dd><a
     href="http://dev.w3.org/geo/api/spec-source-v2.html">http://dev.w3.org/geo/api/spec-source-v2.html</a></dd>

    <dt>Editor:</dt>

    <dd>Andrei Popescu, Google, Inc</dd>
    <dd>Steve Block, Google, Inc</dd>
   </dl>

<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> &copy; 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>&reg;</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p>   <hr>
  </div>

  <h2 class="no-num no-toc" id="abstract">Abstract</h2>

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

  <h2 class="no-num no-toc" id="status">Status of This Document</h2>
  <!-- intro boilerplate (required) -->
<p><em>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 <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
http://www.w3.org/TR/.</em></p>

  <!-- where to send feedback (required) -->

  <p>This document was published by the <a
  href="http://www.w3.org/2008/geolocation/">Geolocation Working Group</a> as both a First Public Working Draft and Last Call Working Draft.  This document builds upon the work done in the <a href="http://www.w3.org/TR/geolocation-API/">Geolocation API</a> by adding the ability to get location represented as a civil address. The difference between the two APIs can be seen in the <a href="http://www.w3.org/2008/geolocation/drafts/API/spec-v1-v2-diff.html">differences document</a>.</p>
<p> When providing feedback, please first refer to the <a href="http://dev.w3.org/geo/api/spec-source-v2.html">Editor's Draft</a> and confirm that the issue has not been addressed already.  If the issue has not been addressed, please send it to the <a
  href="mailto:public-geolocation@w3.org">public-geolocation@w3.org</a> (<a
  href="mailto:public-geolocation-request@w3.org?subject=subscribe">subscribe</a>,
  <a
  href="http://lists.w3.org/Archives/Public/public-geolocation/">archives</a>) mailing list.  The Last Call period ends 15 January 2012. </p>
  <p>All feedback is welcome.</p>
  <!-- stability (required) -->

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

  <!-- required patent boilerplate -->


  <p> This document was produced by a group operating under the <a
   href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
   2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42891/status" rel="disclosure">public list of any patent disclosures</a>
   made in connection with the deliverables of the group; that page also
   includes instructions for disclosing a patent. An individual who has
   actual knowledge of a patent which the individual believes contains <a
   href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
   Claim(s)</a> must disclose the information in accordance with <a
   href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
   6 of the W3C Patent Policy</a>.

  <h2 class="no-num no-toc" id=contents>Table of Contents</h2>
  <!--begin-toc-->

  <ul class=toc>
   <li><a href="#conformance"><span class=secno>1 </span>Conformance
    requirements</a>

   <li><a href="#introduction"><span class=secno>2 </span>Introduction</a>

   <li><a href="#scope"><span class=secno>3 </span>Scope</a>

   <li><a href="#security"><span class=secno>4 </span>Security and privacy
    considerations</a>
    <ul class=toc>
     <li><a href="#privacy_for_uas"><span class=secno>4.1 </span>Privacy
      considerations for implementors of the Geolocation API</a>

     <li><a href="#privacy_for_recipients"><span class=secno>4.2
      </span>Privacy considerations for recipients of location
      information</a>

     <li><a href="#implementation_considerations"><span class=secno>4.3
      </span>Additional implementation considerations</a>
    </ul>

   <li><a href="#api_description"><span class=secno>5 </span>API
    Description</a>
    <ul class=toc>
     <li><a href="#geolocation_interface"><span class=secno>5.1
      </span>Geolocation interface</a>

     <li><a href="#position_options_interface"><span class=secno>5.2
      </span>PositionOptions interface</a>

     <li><a href="#position_interface"><span class=secno>5.3 </span>Position
      interface</a>

     <li><a href="#coordinates_interface"><span class=secno>5.4
      </span>Coordinates interface</a>

     <li><a href="#address_interface"><span class=secno>5.5
      </span>Address interface</a>

     <li><a href="#position_error_interface"><span class=secno>5.6
      </span>PositionError interface</a>
    </ul>

   <li><a href="#usecases"><span class=secno>6 </span>Use-Cases and
    Requirements</a>
    <ul class=toc>
     <li><a href="#usecases_section"><span class=secno>6.1
      </span>Use-Cases</a>

     <li><a href="#requirements_section"><span class=secno>6.2
      </span>Requirements</a>
    </ul>

   <li><a href="#mapping"><span class=secno>7 </span>Mapping of RFC4119 civicLoc format to Address objects</a>

   <li class=no-num><a href="#acknowledgments">Acknowledgments</a>

   <li class=no-num><a href="#references">References</a>
  </ul>
  <!--end-toc-->

  <h2 id=conformance><span class=secno>1 </span>Conformance requirements</h2>

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

  <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
  NOT",-->
   "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. <a href="#ref-rfc2119">[RFC2119]</a></p>
  <!-- XXX but they should be
  marked up -->

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

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

  <p id=hardwareLimitations>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.

  <p>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. <a
   href="#ref-webidl">[WEBIDL]</a>

  <h2 id=introduction><span class=secno>2 </span>Introduction</h2>

  <p><em>This section is non-normative.</em>

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

  <p>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 <a href="#ref-azaloc"
   shape=rect>[AZALOC]</a>, and <a href="#ref-gears" shape=rect>[GEARSLOC]</a>.</p>

  <p>The following code extracts illustrate how to obtain basic location
   information:

  <div class=example>
   <p> Example of a "one-shot" position request.</p>

   <pre>
    function showMap(position) {
      // Show a map centered at (position.coords.latitude, position.coords.longitude).
    }

    // One-shot position request.
    navigator.geolocation.getCurrentPosition(showMap);
    </pre>
  </div>

  <div class=example>
   <p>Example of requesting repeated position updates.</p>

   <pre>
    function scrollMap(position) {
      // Scrolls the map so that it is centered at (position.coords.latitude, position.coords.longitude).
    }

    // Request repeated updates.
    var watchId = navigator.geolocation.watchPosition(scrollMap);

    function buttonClickHandler() {
      // Cancel the updates when the user clicks a button.
      navigator.geolocation.clearWatch(watchId);
    }
    </pre>
  </div>

  <div class=example>
   <p>Example of requesting repeated position updates and handling errors.</p>

   <pre>
    function scrollMap(position) {
      // Scrolls the map so that it is centered at (position.coords.latitude, position.coords.longitude).
    }

    function handleError(error) {
      // Update a div element with error.message.
    }

    // Request repeated updates.
    var watchId = navigator.geolocation.watchPosition(scrollMap, handleError);

    function buttonClickHandler() {
      // Cancel the updates when the user clicks a button.
      navigator.geolocation.clearWatch(watchId);
    }
    </pre>
  </div>

  <div class=example>
   <p>Example of requesting a potentially cached position.</p>

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

    </pre>
  </div>

  <div class=example>
   <p>Forcing the user agent to return a fresh cached position.</p>

   <pre>
    // 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.
    }
    </pre>
  </div>

  <div class=example>
   <p>Forcing the user agent to return any available cached position.</p>

   <pre>
    // 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.
    }
    </pre>
  </div>

  <h2 id=scope><span class=secno>3 </span>Scope</h2>

  <p><em>This section is non-normative.</em>

  <p>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 <a href="#ref-wgs">[WGS84]</a> or in terms
   of a civic address, or both.

  <p>The scope of this specification does not include providing a markup
   language of any kind.

  <p>The scope of this specification does not include defining new URI
   schemes for building URIs that identify geographic locations.

  <h2 id=security><span class=secno>4 </span>Security and privacy
   considerations</h2>

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

  <h3 id="privacy_for_uas"><span class=secno>4.1 </span>Privacy
   considerations for implementors of the Geolocation API</h3>

  <p>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 <a href="#ref-uri">[URI]</a>. 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 <a href="#ref-context">[BROWSINGCONTEXT]</a> is
   navigated to another URL) must be revocable and user agents must respect
   revoked permissions.

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

  <h3 id="privacy_for_recipients"><span id="privacy_for_" class=secno>4.2 </span>Privacy
   considerations for recipients of location information</h3>

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

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

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

  <h3 id="implementation_considerations"><span class=secno>4.3
   </span>Additional implementation considerations</h3>

  <p><em>This section is non-normative.</em>

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

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

  <h2 id="api_description"><span class=secno>5 </span>API Description</h2>

  <h3 id="geolocation_interface"><span class=secno>5.1 </span>Geolocation
   interface</h3>

  <p>The <code><a href="#geolocation">Geolocation</a></code> 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 <code><a
   href="#position">Position</a></code> object, and populating that object
   with appropriate data accordingly.

  <p>Objects implementing the <code>Navigator</code> interface (e.g. the
   <code>window.navigator</code> object) must also implement the <code><a
   href="#navi-geo">NavigatorGeolocation</a></code> interface <a
   href="#ref-navigator">[NAVIGATOR]</a>. An instance of <code><a
   href="#navi-geo">NavigatorGeolocation</a></code> would be then obtained by
   using binding-specific casting methods on an instance of
   <code>Navigator</code>.

  <pre class=idl>
 [NoInterfaceObject]
 interface <dfn id=navi-geo>NavigatorGeolocation</dfn> {
   readonly attribute <a href="#geolocation">Geolocation</a> geolocation;
 };

 Navigator implements NavigatorGeolocation;
  </pre>

  <p><br>

 <pre class=idl>
 [NoInterfaceObject]
 interface <dfn id=geolocation>Geolocation</dfn> {
   void <a href="#get-current-position">getCurrentPosition</a>(in <a href="#position-callback">PositionCallback</a> successCallback,
                           in optional <a href="#error-callback">PositionErrorCallback</a> errorCallback,
                           in optional <a href="#position-options">PositionOptions</a> options);

   long <a href="#watch-position">watchPosition</a>(in <a href="#position-callback">PositionCallback</a> successCallback,
                      in optional <a href="#error-callback">PositionErrorCallback</a> errorCallback,
                      in optional <a href="#position-options">PositionOptions</a> options);

   void <a href="#clear-watch">clearWatch</a>(in long watchId);
 };

 [Callback, NoInterfaceObject]
 interface <dfn id=position-callback>PositionCallback</dfn> {
   void handleEvent(in <a href="#position">Position</a> position);
 };

 [Callback, NoInterfaceObject]
 interface <dfn id=error-callback>PositionErrorCallback</dfn> {
   void handleEvent(in <a href="#position-error">PositionError</a> error);
 };
 </pre>

  <p>The <dfn id=get-current-position><code>getCurrentPosition()</code></dfn>
   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 <code>successCallback</code> must be invoked
   (i.e. the <code>handleEvent</code> operation must be called on the
   callback object) with a new <code>Position</code> object,
   reflecting the current location of the device. If the attempt
   fails, the <code>errorCallback</code> must be invoked with a
   new <code>PositionError</code> object, reflecting the reason for the failure.</p>

  <p>The implementation of the <code>getCurrentPosition</code> method
  should execute the following set of steps:</p>
  <ol>
    <li>Run the following pre-processing steps:
      <ol>
        <li>If <code>successCallback</code> 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 <a href="#ref-webidl">[WEBIDL]</a>.</li>
        <li>If a <code>PositionOptions</code> parameter was present,
        and its <code>maximumAge</code> attribute was defined to a
        non-negative value, assign this value to an internal
        maximumAge variable. If <code>maximumAge</code> was defined
        to a negative value or was not specified, set the internal maximumAge
        variable to <code>0</code>.
        <li>If a <code>PositionOptions</code> parameter was present,
        and its <code>timeout</code> attribute was defined to a
        non-negative value, assign this value to an internal timeout
        variable. If <code>timeout</code> was defined to a negative value,
        set the internal timeout variable to <code>0</code>. If
        <code>timeout</code> was not specified, set the internal timeout
        variable to <code>Infinity</code>.</li>
        <li>If a <code>PositionOptions</code> parameter was present,
        and its <code>enableHighAccuracy</code> attribute was
        defined, assign this value to an internal enableHighAccuracy
        variable. Otherwise, set the internal enableHighAccuracy
        variable to <code>false</code>.</li>
        <li>If a <code>PositionOptions</code> parameter was present, and its
        <code>requireCoords</code> attribute was defined, assign this value to
        an internal requireCoords variable. Otherwise, set the internal
        requireCoords variable to <code>true</code>.</li>
        <li>If a <code>PositionOptions</code> parameter was present, and its
        <code>requestAddress</code> attribute was defined, assign this value to
        an internal requestAddress variable. Otherwise, set the internal
        requestAddress variable to <code>false</code>.</li>
      </ol>
    </li>
    <li>If a cached <code>Position</code> 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
    <code>true</code>, invoke the <code>successCallback</code> with the cached
    <code>Position</code> object as a parameter and exit this set of steps.</li>
    <li> If the value of the timeout variable is <code>0</code>, invoke
    the <code>errorCallback</code> (if present) with a
    new <code>PositionError</code> object whose <code>code</code>
    attribute is set to TIMEOUT and exit this set of steps.</li>
    <li>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
    <code><a href="#high-accuracy">enableHighAccuracy</a></code> and
    <code><a href="#request-address">requestAddress</a></code> for details.</li>
    <li>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 <code>errorCallback</code> (if present)
              with a new <code>PositionError</code> object
              whose <code>code</code> attribute is set to TIMEOUT, and
              exit this set of steps.</li>
    <li>If the operation completes successfully before the timeout
    expires, cancel the pending timer, invoke the <code>successCallback</code>
    with a new <code>Position</code> 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 <code>true</code>, the success criteria
    includes providing non-null values for all relevant attributes of the
    <code>Position</code> object.</li>
    <li>If the operation fails before the timeout expires, cancel the
    pending timer and invoke the <code>errorCallback</code> (if
    present) with a new <code>PositionError</code> object
    whose <code>code</code> is set to POSITION_UNAVAILABLE.</li>
  </ol>

    <p>The <dfn id=watch-position><code>watchPosition()</code></dfn>
   method takes one, two or three arguments. When called, it must immediately
   return a long value that uniquely identifies a <i>watch
   operation</i> 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 <code>successCallback</code> must be invoked
   (i.e. the <code>handleEvent</code> operation must be called on the
   callback object) with a new <code>Position</code> object,
   reflecting the current location of the device. If the attempt
   fails, the <code>errorCallback</code> must be invoked with a
   new <code>PositionError</code> 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 <code><a href="#clear-watch">clearWatch</a></code> method is
   called with the corresponding identifier.</p>

  <p>The implementation of the watch process should execute the
  following set of steps:</p>
  <ol>
    <li>Run the following pre-processing steps:
      <ol>
        <li>If <code>successCallback</code> 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 <a href="#ref-webidl">[WEBIDL]</a>.</li>
        <li>If a <code>PositionOptions</code> parameter was present,
        and its <code>maximumAge</code> attribute was defined to a
        non-negative value, assign this value to an internal
        maximumAge variable. If <code>maximumAge</code> was defined
        to a negative value or was not specified, set the internal maximumAge
        variable to <code>0</code>.
        <li>If a <code>PositionOptions</code> parameter was present,
        and its <code>timeout</code> attribute was defined to a
        non-negative value, assign this value to an internal timeout
        variable. If <code>timeout</code> was defined to a negative value,
        set the internal timeout variable to <code>0</code>. If
        <code>timeout</code> was not specified, set the internal timeout
        variable to <code>Infinity</code>.</li>
        <li>If a <code>PositionOptions</code> parameter was present,
        and its <code>enableHighAccuracy</code> attribute was
        defined, assign this value to an internal enableHighAccuracy
        variable. Otherwise, set the internal enableHighAccuracy
        variable to <code>false</code>.</li>
        <li>If a <code>PositionOptions</code> parameter was present, and its
        <code>requireCoords</code> attribute was defined, assign this value to
        an internal requireCoords variable. Otherwise, set the internal
        requireCoords variable to <code>true</code>.</li>
        <li>If a <code>PositionOptions</code> parameter was present, and its
        <code>requestAddress</code> attribute was defined, assign this value to
        an internal requestAddress variable. Otherwise, set the internal
        requestAddress variable to <code>false</code>.</li>
      </ol>
    </li>
    <li>If a cached <code>Position</code> 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
    <code>true</code>, invoke the <code>successCallback</code> with the cached
    <code>Position</code> object as a parameter and exit this set of steps.</li>
    <li>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).</li>
    <li>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
    <code><a href="#high-accuracy">enableHighAccuracy</a></code> and
    <code><a href="#request-address">requestAddress</a></code> for details.</li>
    <li> Run the following acquisition steps:
      <ol>
        <li>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 <code>errorCallback</code> (if present) with a
        new <code>PositionError</code> object whose <code>code</code>
        attribute is set to TIMEOUT and jump to step 6.</li>

        <li>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 <code>true</code>, the success
        criteria includes providing non-null values for all relevant attributes
        of the <code>Position</code> object.
          <ol>
            <li>Cancel the pending timer. Note that the timer must be
            restarted once this algorithm jumps back to the beginning of the
            acquisition steps.</li>
            <li>If the new position differs significantly from the
              previous position, invoke
              the <code>successCallback</code> with a
              new <code>Position</code> object that reflects the
              result of the acquisition operation.  This step may be
              subject to callback rate limitation
              (<a href="#rate-limit">see below</a>).</li>
          </ol>
        </li>
        <li>Else, if the location acquisition operation reports an
          error before the timeout expires, invoke the <code>errorCallback</code> (if present)
          with a new <code>PositionError</code> object
          whose <code>code</code> is set to POSITION_UNAVAILABLE. This
          step may be subject to callback rate limitation
          (<a href="#rate-limit">see below</a>).</li>
      </ol>
    </li>
    <li>Wait for a system event to be received. When such an event is
    received jump to the acquisition steps above.</li>
  </ol>

  <p id="rate-limit">In step 5.2.2 of the watch process,
  the <code>successCallback</code> 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.</p>

  <p>For both <code>getCurrentPosition</code>
  and <code>watchPosition</code>, the implementation must never invoke
  the <code>successCallback</code> 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 <code>getCurrentPosition</code> or <code>watchPosition</code> steps
  described above. If the user grants permission, the
  appropriate callback must be invoked as described above. If the user
  denies permission, the <code>errorCallback</code> (if present)
  must be invoked with <code>code</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 <code>timeout</code> attribute
  of the <code>PositionOptions</code>
  parameter. The <code>timeout</code> attribute must only apply to the
  location acquisition operation.</p>

  <p>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<a
   href="#ref-unloading">[UNLOADING DOCUMENTS]</a>.</p>

  <p>The <dfn id=clear-watch><code>clearWatch()</code></dfn> method
  takes one argument. When called, it must first check the value of
  the given <dfn id="watchId"><code>watchId</code></dfn> 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
  <code>watchId</code> argument must be immediately stopped and no
  further callbacks must be invoked.</p>

  <h3 id="position_options_interface"><span class=secno>5.2
   </span>PositionOptions interface</h3>

  <p>The <code><a
   href="#get-current-position">getCurrentPosition()</a></code> and <code><a
   href="#watch-position">watchPosition()</a></code> methods accept <code><a
   href="#position-options">PositionOptions</a></code> objects as their third
   argument.

  <p> In ECMAScript, <code><a href="#position-options">PositionOptions</a></code>
   objects are represented using regular native objects with optional
   properties named <code>enableHighAccuracy</code>, <code>timeout</code>,
   <code>maximumAge</code>, <code>requireCoords</code> and
   <code>requestAddress</code>.</p>

  <pre class=idl>
  [Callback, NoInterfaceObject]
  interface <dfn id=position-options>PositionOptions</dfn> {
    attribute boolean <a href="#high-accuracy">enableHighAccuracy</a>;
    attribute long <a href="#timeout">timeout</a>;
    attribute long <a href="#max-age">maximumAge</a>;
    attribute boolean <a href="#require-coords">requireCoords</a>;
    attribute boolean <a href="#request-address">requestAddress</a>;
  };

  </pre>

  <p>In ECMAScript, the <code><a href="#high-accuracy">enableHighAccuracy</a></code>,
   <code><a href="#timeout_error">timeout</a></code> and <code><a
   href="#max-age">maximumAge</a></code> properties are all optional: when
   creating a PositionOptions object, the developer may specify any of these
   properties.

  <p>The <dfn id=high-accuracy><code>enableHighAccuracy</code></dfn>
   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.

  <p>If the <code>PositionOptions</code> parameter
  to <code>getCurrentPosition</code> or <code>watchPosition</code> is
  omitted, the default value used for
  the <code>enableHighAccuracy</code> attribute is <code>false</code>. The same
  default value is used in ECMAScript when
  the <code>enableHighAccuracy</code> property is omitted.

  <p>The <dfn id=timeout><code>timeout</code></dfn> attribute denotes
   the maximum length of time (expressed in milliseconds) that is
   allowed to pass from the call
   to <code><a href="#get-current-position">getCurrentPosition()</a></code>
   or <code><a href="#watch-position">watchPosition()</a></code> until
   the corresponding
   <code>successCallback</code> is invoked. If the implementation is unable
   to successfully acquire a new <code><a
   href="#position">Position</a></code> before the given timeout elapses, and
   no other errors have occurred in this interval, then the corresponding
   <code>errorCallback</code> must be invoked with
   a <code><a href="#position-error">PositionError</a></code> object
   whose <code><a href="#code">code</a></code> attribute is set
   to <a href="#timeout_error">TIMEOUT</a>. Note that the time that is
   spent obtaining the user permission is <b>not</b> included in the period
   covered by the <code>timeout</code>
   attribute. The <code>timeout</code> attribute only applies to the
   location acquisition operation.

  <p>If the <code>PositionOptions</code> parameter
  to <code>getCurrentPosition</code> or <code>watchPosition</code> is
  omitted, the default value used for the <code>timeout</code>
  attribute is <code>Infinity</code>. If a negative value is supplied,
  the <code>timeout</code> value is considered to be <code>0</code>. The same
  default value is used in ECMAScript when the <code>timeout</code>
  property is omitted.

  <p>In case of a <code><a
   href="#get-current-position">getCurrentPosition()</a></code> call, the
   <code>errorCallback</code> would be invoked at most once.

   In case of
   a <code><a href="#watch-position">watchPosition()</a></code>,
   the <code>errorCallback</code> could be invoked repeatedly: the
   first timeout is relative to the
   moment <code><a href="#watch-position">watchPosition()</a></code>
   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
   <code><a href="#position">Position</a></code> object must be acquired.

  <p>The <dfn id=max-age><code>maximumAge</code></dfn> attribute indicates
   that the application is willing to accept a cached position whose age is
   no greater than the specified time in milliseconds. If <code><a
   href="#max-age">maximumAge</a></code> is set to <code>0</code>, the
   implementation must immediately attempt to acquire a new position object.
   Setting the <code><a href="#max-age">maximumAge</a></code> to
   <code>Infinity</code>
   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 <code><a
   href="#max-age">maximumAge</a></code>, then it must acquire a new position
   object. In case of a <code><a
   href="#watch-position">watchPosition()</a></code>, the <code><a
   href="#max-age">maximumAge</a></code> refers to the first position object
   returned by the implementation.</p>

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

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

  <p>If the <code>PositionOptions</code> parameter to
  <code>getCurrentPosition</code> or <code>watchPosition</code> is omitted, the
  default value used for the <code>requireCoords</code> attribute is
  <code>true</code>. The same default value is used in ECMAScript when the
  <code>requireCoords</code> 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.

  <p>The <dfn id=request-address><code>requestAddress</code></dfn> 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 <code>requestAddress</code> is
  <code>true</code> must not imply that the overall location acquisition
  process has failed.

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

  <h3 id="position_interface"><span class=secno>5.3 </span>Position interface</h3>

  <p>The <code><a href="#position">Position</a></code> interface is the
   container for the geolocation information returned by this API. This
   version of the specification allows one attribute of type <code><a
   href="#coordinates">Coordinates</a></code> and a
   <code><a href="#timestamp">timestamp</a></code>.

  <pre class=idl>
  [NoInterfaceObject]
  interface <dfn id=position>Position</dfn> {
    readonly attribute <a href="#coordinates">Coordinates?</a> <a href="#coords">coords</a>;
    readonly attribute <a href="#address_interface">Address?</a> <a href="#address">address</a>;
    readonly attribute DOMTimeStamp <a href="#timestamp">timestamp</a>;
  };
  </pre>

  <p>The <dfn id=coords><code>coords</code></dfn> 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
  <code>coords</code> attribute is optional.

  <p>The <dfn id="address"><code>address</code></dfn> attribute contains a set
  of properties that describe a location on the Earth's surface using a civic
  address. The <code>address</code> attribute is optional.</p>

  <p>The <dfn id=timestamp><code>timestamp</code></dfn> attribute represents
   the time when the <code><a href="#position">Position</a></code> object was
   acquired and is represented as a DOMTimeStamp <a
   href="#ref-domtimestamp">[DOMTIMESTAMP]</a>.

  <p>Note that although both the <code>coords</code> and <code>address</code>
  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.

  <h3 id="coordinates_interface"><span class=secno>5.4 </span>Coordinates
   interface</h3>

  <pre class=idl>
  [NoInterfaceObject]
  interface <dfn id=coordinates>Coordinates</dfn> {
    readonly attribute double? <a href="#lat">latitude</a>;
    readonly attribute double? <a href="#lon">longitude</a>;
    readonly attribute double? <a href="#altitude">altitude</a>;
    readonly attribute double? <a href="#accuracy">accuracy</a>;
    readonly attribute double? <a href="#altitude-accuracy">altitudeAccuracy</a>;
    readonly attribute double? <a href="#heading">heading</a>;
    readonly attribute double? <a href="#speed">speed</a>;
    readonly attribute double? <a href="#vertical-speed">verticalSpeed</a>;
  };
  </pre>

  <p>The geographic coordinate reference system used by the attributes in
   this interface is the World Geodetic System (2d) <a
   href="#ref-wgs">[WGS84]</a>. No other reference system is supported.

  <p>The <dfn id=lat><code>latitude</code></dfn> and <dfn
  id=lon><code>longitude</code></dfn> attributes are geographic coordinates
  specified in decimal degrees. If the implementation cannot provide this
  information, the value of the corresponding attribute must be null.

  <p>The <dfn id=altitude><code>altitude</code></dfn> attribute denotes the
   height of the position, specified in meters above the <a
   href="#ref-wgs">[WGS84]</a> ellipsoid. If the implementation cannot
   provide altitude information, the value of this attribute must be null.

  <p>The <dfn id=accuracy><code>accuracy</code></dfn> 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 <code>latitude</code> or <code>longitude</code> attribute is null,
  the value of this attribute must be null. Otherwise, the value of this
  attribute must be a non-negative real number.

  <p>The <dfn id=altitude-accuracy><code>altitudeAccuracy</code></dfn>
  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.

  <p>The <code><a href="#accuracy">accuracy</a></code> and <code><a
   href="#altitude-accuracy">altitudeAccuracy</a></code> values returned by
   an implementation should correspond to a 95% confidence level.

  <p>The <dfn id=heading><code>heading</code></dfn> attribute denotes the
   direction of travel of the hosting device and is specified in degrees,
   where 0° &le; heading &lt; 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 <code>speed</code> attribute is <code>0</code>), then the value of the
   heading attribute must be NaN.

  <p>The <dfn id=speed><code>speed</code></dfn> 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.

  <p>The <dfn id=vertical-speed><code>verticalSpeed</code></dfn> 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.

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

  <h3 id="address_interface">Address interface</h3>

  <pre class="idl">
  [NoInterfaceObject]
  interface Address {
    readonly attribute DOMString? <a href="#country">country</a>;
    readonly attribute DOMString? <a href="#region">region</a>;
    readonly attribute DOMString? <a href="#county">county</a>;
    readonly attribute DOMString? <a href="#city">city</a>;
    readonly attribute DOMString? <a href="#street">street</a>;
    readonly attribute DOMString? <a href="#streetNumber">streetNumber</a>;
    readonly attribute DOMString? <a href="#premises">premises</a>;
    readonly attribute DOMString? <a href="#postal-code">postalCode</a>;
  };
  </pre>

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

  <p>The <dfn id="country"><code>country</code></dfn> attribute is
  specified using the two-letter <a href="#ref-iso3166">[ISO
  3166-1]</a> code.</p>

  <p>The <dfn id="region"><code>region</code></dfn> denotes the name
  of a country subdivision (e.g. the state name in the US).</p>
  <p>The <dfn id="county"><code>county</code></dfn> denotes the name
  of a land area within the larger <code>region</code>.</p>
  <p>The <dfn id="city"><code>city</code></dfn> reflects the name of
  the city.</p>
  <p>The <dfn id="street"><code>street</code></dfn> reflects the name
  of the street.</p>
  <p>The <dfn id="streetNumber"><code>streetNumber</code></dfn>
  reflects the location's street number.</p>
  <p>The <dfn id="premises"><code>premises</code></dfn> denotes the
  details of the premises, such as a building name, block of flats,
  etc.</p>
  <p>The <dfn id="postal-code"><code>postalCode</code></dfn> reflects
  the postal code of the location (e.g. the zip code in the US).</p>

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

  <h3 id="position_error_interface"><span class=secno>5.5
   </span>PositionError interface</h3>

  <pre class=idl>
  [NoInterfaceObject]
  interface <dfn id=position-error>PositionError</dfn> {
    const unsigned short <a href="#permission_denied_error">PERMISSION_DENIED</a> = 1;
    const unsigned short <a href="#position_unavailable_error">POSITION_UNAVAILABLE</a> = 2;
    const unsigned short <a href="#timeout_error">TIMEOUT</a> = 3;
    readonly attribute unsigned short <a href="#code">code</a>;
    readonly attribute DOMString <a href="#message">message</a>;
  };
  </pre>

  <p>The <dfn id=code><code>code</code></dfn> attribute must return the
   appropriate code from the following list:

  <dl>
   <dt><dfn id="permission_denied_error"><code>PERMISSION_DENIED</code></dfn>
    (numeric value 1)

   <dd>The location acquisition process failed because the document
    does not have permission to use the Geolocation API.

   <dt><dfn
    id="position_unavailable_error"><code>POSITION_UNAVAILABLE</code></dfn>
    (numeric value 2)

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

   <dt><dfn id="timeout_error"><code>TIMEOUT</code></dfn> (numeric value 3)

   <dd>The length of time specified by the <code><a href="#timeout">timeout</a></code>
    property has elapsed before the implementation could successfully acquire a
    new <code><a href="#position">Position</a></code> object.
  </dl>

  <p>The <dfn id=message><code>message</code></dfn> 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.

  <h2 id=usecases><span class=secno>6 </span>Use-Cases and Requirements</h2>

  <h3 id="usecases_section"><span class=secno>6.1 </span>Use-Cases</h3>

  <h4 id="usecase_find_poi"><span class=secno>6.1.1 </span>Find points of
   interest in the user's area</h4>

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

  <h4 id="usecase_content_annotation"><span class=secno>6.1.2
   </span>Annotating content with location information</h4>

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

  <h4 id="usecase_show_position"><span class=secno>6.1.3 </span>Show the
   user's position on a map</h4>

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

  <h4 id="usecase_turn_by_turn"><span class=secno>6.1.4 </span>Turn-by-turn
   route navigation</h4>

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

  <h4 id="usecase_poi_alert"><span class=secno>6.1.5 </span>Alerts when
   points of interest are in the user's vicinity</h4>

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

  <h4 id="usecase_local_info"><span class=secno>6.1.6 </span>Up-to-date local
   information</h4>

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

  <h4 id="usecase_social_networking"><span class=secno>6.1.7
   </span>Location-tagged status updates in social networking applications</h4>

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

  <h4 id="usecase_form_filling"><span class=secno>6.1.8</span>
   Automatic form filling.
  </h4>

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

  <h3 id="requirements_section"><span class=secno>6.2 </span>Requirements</h3>

  <h4 id="req_latlong"><span class=secno>6.2.1 </span>The Geolocation API
   must provide a way for an application to receive location data in terms
   of a pair of latitude and longitude coordinates.</h4>

  <h4 id="req_accuracy"><span class=secno>6.2.2 </span>The Geolocation API
   must provide a way for an application to receive information about the
   accuracy of the retrieved location data.</h4>

  <h4 id="req_oneshot"><span class=secno>6.2.3 </span>The Geolocation API
   must support "one-shot" position updates.</h4>

  <h4 id="req_updates"><span class=secno>6.2.4 </span>The Geolocation API
   must allow an application to register to receive updates when the position
   of the hosting device changes.</h4>

  <h4 id="req_last_known"><span class=secno>6.2.5 </span>The Geolocation API
   must allow an application to request a cached position whose age is no
   greater than a specified value.</h4>

  <h4 id="req_errors"><span class=secno>6.2.6 </span>The Geolocation API must
   provide a way for the application to receive updates about errors that may
   have occurred while obtaining a location fix.</h4>

  <h4 id="req_request_acuracy"><span class=secno>6.2.7 </span>The Geolocation
   API must allow an application to specify a desired accuracy level of the
   location information.</h4>

  <h4 id="req_source_agnostic"><span class=secno>6.2.8 </span>The Geolocation
   API must be agnostic to the underlying sources of location information.</h4>

  <h4 id="req_provide_address"><span class=secno>6.2.9 </span>The Geolocation
   API must provide a way for an application to receive location data as a civic address.</h4>

  <h4 id="req_select_type"><span class=secno>6.2.10 </span>The Geolocation
   API must allow an application to specify the type of location information
   that it wishes to receive.</h4>

  <h4 id="req_backwards_compatible"><span class=secno>6.2.11 </span>The Geolocation
   API must be backwards compatible with all previously published versions of this API.</h4>

  <h2 id=mapping><span class=secno>7 </span>Mapping of RFC4119 civicLoc format to <a href="#address_interface"><code>Address</code></a> objects</h2>

  <p><em>This section is non-normative.</em>

  <p>This section proposes a mapping of the RFC4119 <a href="#ref-rfc4119">[RFC4119]</a> civicLoc format to
  <a href="#address_interface"><code>Address</code></a> objects.

  <table>
	<tr>
  <th>civicLoc label</th><th>Address interface attribute</th><th>Example</th></tr>
  <tr>
    <td>country</td><td><a href="#country"><code>country</code></a></td><td></td>
  </tr>
  <tr>
    <td>A1</td><td><a href="#region"><code>region</code></a></td><td></td>
  </tr>
  <tr>
    <td>A2</td><td><a href="#county"><code>county</code></a></td><td></td>
  </tr>
  <tr>
    <td>A3, A4, A5</td><td><a href="#city"><code>city</code></a></td><td>'Battersea, London'</td>
  </tr>
  <tr>
    <td>A6, PRD, POD, STS</td><td><a href="#street"><code>street</code></a></td><td>'Carriage Drive North'</td>
  </tr>
  <tr>
    <td>HNO, HNS</td><td><a href="#streetNumber"><code>streetNumber</code></a></td><td>'78A'</td>
  </tr>
  <tr>
    <td>LMK, NAM</td><td><a href="#premises"><code>premises</code></a></td><td>'Google UK, Belgrave House'</td>
  </tr>
  <tr>
    <td>PC</td><td><a href="#postal-code"><code>postalCode</code></a></td><td></td>
  </tr>
  </table>


  <h2 class=no-num id=acknowledgments>Acknowledgments</h2>

  <p>Alec Berntson, Alissa Cooper, Steve Block, Greg Bolsinga, Lars Erik Bolstad, Aaron Boodman,
   Dave Burke, Chris Butler, Max Froumentin, Shyam Habarakada, Marcin
   Hanclik, Ian Hickson, Brad Lassey, Angel Machin, Cameron McCormack, Daniel
   Park, Stuart Parmenter, Olli Pettay, Chris Prince, Arun Ranganathan, Aza
   Raskin, Carl Reed, Thomas Roessler, Dirk Segers, Allan Thomson, Martin
   Thomson, Doug Turner, Erik Wilde, Matt Womer, Mohamed Zergaoui

  <h2 class=no-num id=references>References</h2>

  <dl>
   <dt><a id=ref-azaloc>[AZALOC]</a>

   <dd><em>(Non-normative)</em> <cite><a
    href="http://www.azarask.in/blog/post/geolocation-in-firefox-and-beyond/">Geolocation
    in Firefox and Beyond</a></cite>, Aza Raskin. See
    http://azarask.in/blog/post/geolocation-in-firefox-and-beyond

   <dt><a id=ref-context>[BROWSINGCONTEXT]</a>

   <dd><cite><a
    href="http://dev.w3.org/html5/spec/Overview.html#browsing-context">The
    browsing context in HTML5</a></cite>, Ian Hickson, David Hyatt, Editors.  World Wide Web Consortium.  See
    http://dev.w3.org/html5/spec/Overview.html#browsing-context

   <dt><a id=ref-uri>[URI]</a>

   <dd><cite><a href="http://www.ietf.org/rfc/rfc2396.txt">Uniform Resource Identifiers (URI): Generic Syntax
    </a></cite>.T. Berners-Lee, R. Fielding, L. Masinter, Editors. Internet Engineering Task Force.
    See http://www.ietf.org/rfc/rfc2396.txt

   <dt><a id=ref-navigator>[NAVIGATOR]</a>

   <dd><cite><a
    href="http://www.w3.org/TR/2009/WD-html5-20090423/browsers.html#navigator">Navigator
    interface in HTML5</a></cite>, Ian Hickson, David Hyatt, Editors.  World Wide Web Consortium.  See
	http://www.w3.org/TR/2009/WD-html5-20090423/browsers.html#navigator

   <dt><a id=ref-domtimestamp>[DOMTIMESTAMP]</a>

   <dd><cite><a
    href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Core-DOMTimeStamp">The
    DOMTimeStamp Type</a></cite>,
	Arnaud Le Hors, Philippe Le Hégaret, Gavin Nicol, Lauren Wood, Mike Champion, Steve Byrne, Editors. World Wide Web Consortium, 7 April 2004.  See
    http://www.w3.org/TR/DOM-Level-3-Core/core.html#Core-DOMTimeStamp

   <dt><a id=ref-gears>[GEARSLOC]</a>

   <dd><em>(Non-normative)</em> <cite><a
    href="http://code.google.com/apis/gears/api_geolocation.html">Gears
    Geolocation API</a></cite>. See http://code.google.com/apis/gears/api_geolocation.html

   <dt><a id="ref-iso3166">[ISO3166]</a></dt>

   <dd><cite><a href="http://www.iso.org/iso/iso-3166-1_decoding_table">ISO
   3166-1 decoding table</a></cite>. http://www.iso.org/iso/iso-3166-1_decoding_table</dd>

   <dt><a id=ref-rfc2119>[RFC2119]</a>

   <dd><cite><a href="http://www.ietf.org/rfc/rfc2119.txt">Key words for use
    in RFCs to Indicate Requirement Levels</a></cite>, Scott Bradner.  Internet Engineering Task Force, March 1997. See
    http://www.ietf.org/rfc/rfc2119.txt

   <dt><a id=ref-rfc3066>[RFC3066]</a>

   <dd><cite><a href="http://www.ietf.org/rfc/rfc3066.txt">Tags for the
    Identification of Languages</a></cite>, Harald Tveit Alvestrand.  Internet Engineering Task Force, January 2001. See
    http://www.ietf.org/rfc/rfc3066.txt

   <dt><a id=ref-rfc4119>[RFC4119]</a>

   <dd><cite><a href="http://www.ietf.org/rfc/rfc4119.txt">A Presence-based GEOPRIV Location Object Format</a></cite>,
   J. Peterson.  Internet Engineering Task Force, December 2005. See
   http://www.ietf.org/rfc/rfc4119.txt

   <dt><a id=ref-unloading>[UNLOADING DOCUMENTS]</a>

   <dd><em>(Non-normative)</em><cite> <a
    href="http://dev.w3.org/html5/spec/Overview.html#unloading-document-cleanup-steps">Unloading
    documents cleanup steps in  HTML5</a></cite>, Ian Hickson, David Hyatt, Editors.  World Wide Web Consortium.  See
	http://dev.w3.org/html5/spec/Overview.html#unloading-document-cleanup-steps

   <dt><a id=ref-webidl>[WEBIDL]</a>

   <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, Cameron McCormack, Editor.  World Wide Web Consortium, 19 December 2008. See
    http://dev.w3.org/2006/webapi/WebIDL/

   <dt><a id=ref-wgs>[WGS84]</a>

   <dd><cite><a
    href="http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf">National
    Imagery and Mapping Agency Technical Report 8350.2, Third
    Edition</a></cite>.  National Imagery and Mapping Agency, 3 January 2000.  See
    http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf
  </dl>
</body>
</html>