Navigator.Geolocation

Originally published on June 1, 2016.
Last updated on June 15, 2016.

The navigator.geolocation object is found in most modern browsers.

Browser Availability

It’s available in desktop browsers:

  • Chrome 5+
  • Firefox 3.5+ (Gecko 1.9.1+)
  • Internet Explorer 9+
  • Opera 10.60+ (It was removed in 15.0 and reintroduced in 16.0.)
  • Safari 5+

It’s available in mobile browsers:

  • Android ?
  • Chrome for Android ?
  • Firefox Mobile 4.0+ (Gecko 4.0+)
  • IE Mobile ?
  • Opera Mobile 10.60+
  • Safari Mobile ?

Geolocation API

Interfaces

Coordinates

[NoInterfaceObject]
interface Coordinates {
    readonly attribute double latitude;
    readonly attribute double longitude;
    readonly attribute double altitude;
    readonly attribute double accuracy;
    readonly attribute double altitudeAccuracy;
    readonly attribute double heading;
    readonly attribute double speed;
};

The geographic coordinate reference system used by the attributes in this interface is the World Geodetic System (2d) [WGS84]. No other reference system is supported.

latitude
This attribute is the geographic latitude specified in decimal degrees.

longitude
This attribute is the geographic longitude specified in decimal degrees.

altitude
This attribute denotes the height of the position, specified in meters above the [WGS84] ellipsoid. If the implementation cannot provide altitude information, the value of this attribute must be null.

accuracy
This attribute denotes the accuracy level of the latitude and longitude coordinates. It is specified in meters and must be supported by all implementations. The value of the accuracy attribute must be a non-negative real number. The accuracy value returned by an implementation should correspond to a 95% confidence level.

altitudeAccuracy
This attribute is specified in meters. If the implementation cannot provide altitude information, the value of this attribute must be null. Otherwise, the value of the altitudeAccuracy attribute must be a non-negative real number. The altitudeAccuracy value returned by an implementation should correspond to a 95% confidence level.

heading
This attribute denotes the direction of travel of the hosting device and is specified in degrees, where 0° ≤ heading < 360°, counting clockwise relative to the true north. If the implementation cannot provide heading information, the value of this attribute must be null. If the hosting device is stationary (i.e. the value of the speed attribute is 0), then the value of the heading attribute must be NaN.

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

Geolocation

[NoInterfaceObject]
interface Geolocation { 
    void getCurrentPosition(PositionCallback successCallback,
                           optional PositionErrorCallback errorCallback,
                           optional PositionOptions options);
    long watchPosition(PositionCallback successCallback,
                      optional PositionErrorCallback errorCallback,
                      optional PositionOptions options);
    void clearWatch(long watchId);
};
callback PositionCallback = void (Position position);
callback PositionErrorCallback = void (PositionError positionError);

NavigatorGeolocation

[NoInterfaceObject]
interface NavigatorGeolocation {
    readonly attribute Geolocation geolocation;
};
Navigator implements NavigatorGeolocation;

Position

[NoInterfaceObject]
interface Position {
    readonly attribute Coordinates coords;
    readonly attribute DOMTimeStamp timestamp;
};

PositionError

[NoInterfaceObject]
interface PositionError {
    const unsigned short PERMISSION_DENIED = 1;
    const unsigned short POSITION_UNAVAILABLE = 2;
    const unsigned short TIMEOUT = 3;
    readonly attribute unsigned short code;
    readonly attribute DOMString message;
};

The code attribute returns the appropriate code from the following list:

PERMISSION_DENIED (numeric value 1)
The location acquisition process failed because the document does not have permission to use the Geolocation API.

POSITION_UNAVAILABLE (numeric value 2)
The position of the device could not be determined. For instance, one or more of the location providers used in the location acquisition process reported an internal error that caused the process to fail entirely.

TIMEOUT (numeric value 3)
The length of time specified by the timeout property has elapsed before the implementation could successfully acquire a new Position object.

The message attribute returns 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.

PositionOptions

[NoInterfaceObject]
interface PositionOptions {
    attribute boolean enableHighAccuracy;
    attribute long timeout;
    attribute long maximumAge;
};

Methods

The geolocation object has three methods:

  • getCurrentPosition()
  • watchPosition()
  • clearWatch()

getCurrentPosition()

void getCurrentPosition(successCallback, errorCallback, options);

The getCurrentPosition() method takes one, two or three arguments. When called, it immediately returns and then asynchronously attempts to obtain the current location of the device. If the attempt is successful, the successCallback is invoked with a new Position object, reflecting the current location of the device. If the attempt fails, the errorCallback is invoked with a new PositionError object, reflecting the reason for the failure.

PositionCallback successCallback

PositionErrorCallback errorCallback (optional)

PositionOptions options (optional)

watchPosition()

This section will have content soon.

clearWatch()

This section will have content soon.

JavaScript Example

<script>// <![CDATA[
if ("geolocation" in navigator) {
    /* Geolocation is available. */
    var latitude, longitude, altitude, accuracy, altitudeAccuracy, heading, speed; /* Coordinates */
    var options = {
        enableHighAccuracy: true,
        timeout: 5000,
        maximumAge: 0
    }
    function success(pos) {
        var crd = pos.coords;
        latitude = crd.latitude;
        longitude = crd.longitude;
        altitude = crd.altitude;
        accuracy = crd.accuracy;
        altitudeAccuracy = crd.altitudeAccuracy;
        heading = crd.heading;
        speed = crd.speed;
        var googleMapsLink = "http://maps.google.com/?q=" + latitude + ","       ↩
            + longitude + "&t=k&z=20";
        document.getElementById("geolocation-demo").innerHTML =                  ↩
            "It looks like you are at "                                          ↩
            + latitude + " "                                                     ↩
            + longitude + ", ± "                                                 ↩
            + accuracy + " meters.<br />See it on <a href=\""                    ↩
            + googleMapsLink + "\" target=\"_blank\">Google Maps</a>.<br />";
    }
    function error(err) {
        document.getElementById("geolocation-demo").innerHTML = 
            "ERROR(" + err.code + "): " + err.message + "<br />";                ↩
    }
    navigator.geolocation.getCurrentPosition(success, error, options);
} else {
    /* Geolocation is not available. */
    document.getElementById("geolocation-demo").innerHTML = 
        "Geolocation is not available.<br />";                                   ↩
}
// ]]></script>
<p id="geolocation-demo"></p>

Sometimes it takes a few seconds to return the geolocation information. Please be patient.

The geolocation information is calculated on YOUR device. IX23 does not have access to this information.

References

Popescu, Andrei (Editor). “Geolocation API Specification”. W3C Recommendation. World Wide Web Consortium (W3C). October 24, 2013. Accessed May 31, 2016.