Using geolocation

  • Revision slug: Using_geolocation
  • Revision title: Using geolocation
  • Revision id: 11746
  • Created:
  • Creator: Chtitux
  • Is current revision? No
  • Comment 3 words added, 6 words removed

Revision Content

{{ fx_minversion_header("3") }}

Firefox 3.1 and later support the Geolocation API; this allows the user provide his location to web applications if he so desires.  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.");
}

The lastPosition attribute

You can get the last determined position quickly, without querying the location determination system (whether that's GPS, WiFi hotspot location services, or actually asking the user), using the lastPosition attribute:

Position myPosition = navigator.geolocation.lastPosition;

This lets you obtain an approximate position without waiting for the hardware to be polled.

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, as well as an optional enableHighAccuracy flag (not currently supported).

navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.latitude, position.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.latitude, position.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:

latitude
The user's current latitude, in degrees, as a double.
longitude
The user's current longitude, in degrees, as a double.
altitude
The user's current altitude, in meters, as a double.  Zero if the device doesn't support altitude detection.
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.
timestamp
The time at which the reading was taken, as a DOMTimeStamp.

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.
message
A human readable error message, suitable for use in logs.

See also

  • {{ Interface("nsIGeolocationProvider") }}
  • {{ Interface("nsIDOMGeolocation") }}
  • {{ Interface("nsIDOMGeoPosition") }}
  • {{ Interface("nsIDOMGeoPositionCallback") }}
  • {{ Interface("nsIDOMGeoPositionError") }}
  • {{ Interface("nsIDOMGeoPositionErrorCallback") }}
  • {{ Interface("nsIDOMGeoPositionOptions") }}
  • {{ Interface("nsIDOMNavigatorGeolcation") }}

 

Revision Source

<p>{{ fx_minversion_header("3") }}</p>
<p>Firefox 3.1 and later support the Geolocation API; this allows the user provide his location to web applications if he so desires.  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>The lastPosition attribute</h3>
<p>You can get the last determined position quickly, without querying the location determination system (whether that's GPS, WiFi hotspot location services, or actually asking the user), using the lastPosition attribute:</p>
<pre>Position myPosition = navigator.geolocation.lastPosition;
</pre>
<p>This lets you obtain an approximate position without waiting for the hardware to be polled.</p>
<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, as well as an optional <code>enableHighAccuracy</code> flag (not currently supported).</p>
<pre class="brush: js">navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.latitude, position.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.latitude, position.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>
<dl> <dt>latitude</dt><dd>The user's current latitude, in degrees, as a <code>double</code>.</dd> <dt>longitude</dt><dd>The user's current longitude, in degrees, as a <code>double</code>.</dd> <dt>altitude</dt><dd>The user's current altitude, in meters, as a <code>double</code>.  Zero if the device doesn't support altitude detection.<br>
</dd> <dt>accuracy</dt><dd>The accuracy of position information, in meters, as a <code>double</code>.<br>
</dd> <dt>altitudeAccuracy</dt><dd>The accuracy of altitude information, in meters, as a <code>double</code>.  Zero if the device doesn't support altitude detection.</dd> <dt>heading</dt><dd>The current heading at which the user is moving, in degrees, as a <code>double</code>.</dd> <dt>speed</dt><dd>The speed at which the user is moving, in meters per second, as a <code>double</code>.</dd> <dt>timestamp</dt><dd>The time at which the reading was taken, as a <code>DOMTimeStamp</code>.</dd> </dl>
<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.</dd><dt>message</dt><dd>A human readable error message, suitable for use in logs.</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>
</ul>
<p> </p>
Revert to this revision