Using geolocation

  • Revision slug: Using_geolocation
  • Revision title: Using geolocation
  • Revision id: 11754
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 4 words added, 5 words removed

Revision Content

{{ fx_minversion_header("3") }}

Firefox 3.5 and later support the Geolocation API; this allows the user to provide their location to web applications if they so desire.  For privacy reasons, the user is asked to confirm permission to report location information.

Firefox does not currently include any built-in geolocation data providers, so by default no location information can be provided.  A basic one, written by Doug Turner, that allows the user to manually enter their position using latitude and longitude is available for download.

Note: If your interest is in writing a geolocation provider -- a service which can be queried for the user's location -- please see {{ Interface("nsIGeolocationProvider") }}.

The geolocation object

The geolocation API is published through a geolocation child object within the navigator object.  If the object exists, geolocation services are available.  You can test for the presence of geolocation thusly:

if (navigator.geolocation) {
  /* geolocation is available */
} else {
  alert("I'm sorry, but geolocation services are not supported by your browser.");
}

Getting the current position

To obtain the user's current location, you can call the getCurrentPosition() method.  This initiates an asynchronous request to detect the user's position, and queries the positioning hardware to get up-to-date information.  When the position is determined, a specified callback routine is executed.  You can optionally provide a second callback to be executed if an error occurs.  A third optional parameter is an options interface where you can set the maximum age of the request, and the time to wait for a request.

navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
});

The above example will cause the do_something() function to execute when the location is obtained.

Watching the current position

If you want to be kept abreast of changes in the user's location, you can set up a callback that is called periodically with updated position information.  This is done using the watchPosition() function, which has the same input parameters as getCurrentPosition().  Its callback is called repeatedly instead of just once.  The error callback, which is optional just as it is for getCurrentPosition(), is called only once, if there will never be valid results returned.

var watchID = navigator.geolocation.watchPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
}
);

The watchPosition() method returns an ID number that can be used to uniquely identify the requested position watcher; you use this value in tandem with the clearWatch() method to stop watching the user's location.

navigator.geolocation.clearWatch(watchID);

Describing a position

The user's location is described using a Position object, which has the following fields:

 

 

timestamp
The time at which the reading was taken, as a DOMTimeStamp.
coords
The coords object consists of the following:

 

          latitude

          The user's current latitude, in degrees, as a double.

          longitude
          The user's current longitude, in degrees, as a double.

          accuracy
          The accuracy of position information, in meters, as a double.

          altitudeAccuracy
          The accuracy of altitude information, in meters, as a double.  Zero if the device doesn't support altitude detection.

          heading
          The current heading at which the user is moving, in degrees, as a double.

          speed
          The speed at which the user is moving, in meters per second, as a double.

Handling errors

The error callback, if provided when calling getCurrentPosition() or watchPosition(), has the following signature:

function errorCallback(PositionError error);

The PositionError structure has the following fields:

code
A numeric error code which much be one of the following:
UNKNOWN_ERROR (numeric value 0)
The location acquisition process failed due to an error not covered by the definition of any other error code in this interface.
PERMISSION_DENIED (numeric value 1)
The location acquisition process failed because the application origin does not have permission to use the Geolocation API.
POSITION_UNAVAILABLE (numeric value 2)
The position of the device could not be determined. One or more of the location providers used in the location acquisition process reported an internal error that caused the process to fail entirely.
TIMEOUT (numeric value 3)
The specified maximum length of time has elapsed before the implementation could successfully acquire a new Position object.

message
A human readable error message, suitable for use in logs and debugging -- but not for display to the user.

See also

  • {{ Interface("nsIGeolocationProvider") }}
  • {{ Interface("nsIDOMGeolocation") }}
  • {{ Interface("nsIDOMGeoPosition") }}
  • {{ Interface("nsIDOMGeoPositionCallback") }}
  • {{ Interface("nsIDOMGeoPositionError") }}
  • {{ Interface("nsIDOMGeoPositionErrorCallback") }}
  • {{ Interface("nsIDOMGeoPositionOptions") }}
  • {{ Interface("nsIDOMNavigatorGeolcation") }}
  • Geolocation API on w3.org 

 

Revision Source

<p>{{ fx_minversion_header("3") }}</p>
<p>Firefox 3.5 and later support the Geolocation API; this allows the user to provide their location to web applications if they so desire.  For privacy reasons, the user is asked to confirm permission to report location information.</p>
<p>Firefox does not currently include any built-in geolocation data providers, so by default no location information can be provided.  A basic one, written by Doug Turner, that allows the user to manually enter their position using latitude and longitude is <a class="link-https" href="https://addons.mozilla.org/en-US/firefox/addon/8420" title="https://addons.mozilla.org/en-US/firefox/addon/8420">available for download</a>.</p>
<div class="note"><strong>Note:</strong> If your interest is in writing a geolocation provider -- a service which can be queried for the user's location -- please see {{ Interface("nsIGeolocationProvider") }}.</div>
<h2>The geolocation object</h2>
<p>The geolocation API is published through a <code>geolocation</code> child object within the <code>navigator</code> object.  If the object exists, geolocation services are available.  You can test for the presence of geolocation thusly:</p>
<pre class="brush: js">if (navigator.geolocation) {
  /* geolocation is available */
} else {
  alert("I'm sorry, but geolocation services are not supported by your browser.");
}
</pre>
<h3>Getting the current position</h3>
<p>To obtain the user's current location, you can call the <code>getCurrentPosition()</code> method.  This initiates an asynchronous request to detect the user's position, and queries the positioning hardware to get up-to-date information.  When the position is determined, a specified callback routine is executed.  You can optionally provide a second callback to be executed if an error occurs.  A third optional parameter is an options interface where you can set the maximum age of the request, and the time to wait for a request.</p>
<pre class="brush: js">navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
});</pre>
<p>The above example will cause the <code>do_something()</code> function to execute when the location is obtained.</p>
<h3>Watching the current position</h3>
<p>If you want to be kept abreast of changes in the user's location, you can set up a callback that is called periodically with updated position information.  This is done using the <code>watchPosition()</code> function, which has the same input parameters as <code>getCurrentPosition()</code>.  Its callback is called repeatedly instead of just once.  The error callback, which is optional just as it is for <code>getCurrentPosition()</code>, is called only once, if there will never be valid results returned.</p>
<pre class="brush: js">var watchID = navigator.geolocation.watchPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
}
);</pre>
<p>The <code>watchPosition()</code> method returns an ID number that can be used to uniquely identify the requested position watcher; you use this value in tandem with the <code>clearWatch()</code> method to stop watching the user's location.</p>
<pre>navigator.geolocation.clearWatch(watchID);
</pre>
<h2>Describing a position</h2>
<p>The user's location is described using a Position object, which has the following fields:</p>
<p> </p>
<p> </p><dt>timestamp</dt>The time at which the reading was taken, as a <code>DOMTimeStamp</code>.<dt>coords<br>
</dt>The coords object consists of the following:
<p> </p>
<p><strong>          latitude</strong></p>
<p><strong>          </strong>The user's current latitude, in degrees, as a double.</p>
<p><strong>          </strong><strong>longitude</strong><br>
<strong>          </strong>The user's current longitude, in degrees, as a double.</p>
<p><strong>          </strong><strong>accuracy</strong><br>
<strong>          </strong>The accuracy of position information, in meters, as a double.</p>
<p><strong>          </strong><strong>altitudeAccuracy</strong><br>
<strong>          </strong>The accuracy of altitude information, in meters, as a double.  Zero if the device doesn't support altitude detection.</p>
<p><strong>          </strong><strong>heading</strong><br>
<strong>          </strong>The current heading at which the user is moving, in degrees, as a double.</p>
<p><strong>          </strong><strong>speed</strong><br>
<strong>          </strong>The speed at which the user is moving, in meters per second, as a double.</p>
<h2>Handling errors</h2>
<p>The error callback, if provided when calling <code>getCurrentPosition()</code> or <code>watchPosition()</code>, has the following signature:</p>
<pre>function errorCallback(PositionError error);
</pre>
<p>The <code>PositionError</code> structure has the following fields:</p>
<dl><dt>code</dt><dd>A numeric error code which much be one of the following:<br>
</dd><dt><dfn id="unknown_error"><code>UNKNOWN_ERROR</code></dfn> (numeric value 0)</dt><dd>The location acquisition process failed due to an error not covered by the definition of any other error code in this interface.</dd><dt><dfn id="permission_denied_error"><code>PERMISSION_DENIED</code></dfn> (numeric value 1)</dt><dd>The location acquisition process failed because the application origin does not have permission to use the Geolocation API.</dd><dt><dfn id="position_unavailable_error"><code>POSITION_UNAVAILABLE</code></dfn> (numeric value 2)</dt><dd>The position of the device could not be determined. One or more of the location providers used in the location acquisition process reported an internal error that caused the process to fail entirely.</dd><dt><dfn id="timeout_error"><code>TIMEOUT</code></dfn> (numeric value 3)</dt><dd>The specified maximum length of time has elapsed before the implementation could successfully acquire a new Position object.</dd><dd><br>
</dd><dt>message</dt><dd>A human readable error message, suitable for use in logs and debugging -- but not for display to the user.<br>
</dd></dl>
<h2>See also</h2>
<ul> <li>{{ Interface("nsIGeolocationProvider") }}</li> <li>{{ Interface("nsIDOMGeolocation") }}</li> <li>{{ Interface("nsIDOMGeoPosition") }}</li> <li>{{ Interface("nsIDOMGeoPositionCallback") }}</li> <li>{{ Interface("nsIDOMGeoPositionError") }}</li> <li>{{ Interface("nsIDOMGeoPositionErrorCallback") }}</li> <li>{{ Interface("nsIDOMGeoPositionOptions") }}</li> <li>{{ Interface("nsIDOMNavigatorGeolcation") }}</li> <li><a class="external" href="http://www.w3.org/TR/2008/WD-geolocation-API-20081222/" title="http://www.w3.org/TR/2008/WD-geolocation-API-20081222/">Geolocation API on w3.org</a> </li>
</ul>
<p> </p>
Revert to this revision