Geolocation API

Secure context
This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The Geolocation API allows the user to provide their location to web applications if they so desire. For privacy reasons, the user is asked for permission to report location information.

WebExtensions that wish to use the Geolocation object must add the "geolocation" permission to their manifest. The user's operating system will prompt the user to allow location access the first time it is requested.

Concepts and usage

You will often want to retrieve a user's location information in your web app, for example to plot their location on a map, or display personalized information relevant to their location.

The Geolocation API is accessed via a call to navigator.geolocation; this will cause the user's browser to ask them for permission to access their location data. If they accept, then the browser will use the best available functionality on the device to access this information (for example, GPS).

The developer can now access this location information in a couple of different ways:

In both cases, the method call takes up to three arguments:

  • A mandatory success callback: If the location retrieval is successful, the callback executes with a GeolocationPosition object as its only parameter, providing access to the location data.
  • An optional error callback: If the location retrieval is unsuccessful, the callback executes with a GeolocationPositionError object as its only parameter, providing access information on what went wrong.
  • An optional PositionOptions object, which provides options for retrieval of the position data.

For further information on Geolocation usage, read Using the Geolocation API.

Interfaces

Geolocation
The main class of this API — contains methods to retrieve the user's current position, watch for changes in their position, and clear a previously-set watch.
GeolocationPosition
Represents the position of a user. A GeolocationPosition instance is returned by a successful call to one of the methods contained inside Geolocation, inside a success callback, and contains a timestamp plus a GeolocationCoordinates object instance.
GeolocationCoordinates
Represents the coordinates of a user's position; a GeolocationCoordinates instance contains latitude, longitude, and other important related information.
GeolocationPositionError
A GeolocationPositionError is returned by an unsuccessful call to one of the methods contained inside Geolocation, inside an error callback, and contains an error code and message.
Navigator.geolocation
The entry point into the API. Returns a Geolocation object instance, from which all other functionality can be accessed.

Dictionaries

PositionOptions
Represents an object containing options to pass in as a parameter of Geolocation.getCurrentPosition() and Geolocation.watchPosition().

Examples

In the following example the Geolocation API is used to retrieve the user's latitude and longitude. If sucessful, the available hyperlink is populated with an openstreetmap.org URL that will show their location.

HTML

<button id = "find-me">Show my location</button><br/>
<p id = "status"></p>
<a id = "map-link" target="_blank"></a>

JavaScript

function geoFindMe() {

  const status = document.querySelector('#status');
  const mapLink = document.querySelector('#map-link');

  mapLink.href = '';
  mapLink.textContent = '';

  function success(position) {
    const latitude  = position.coords.latitude;
    const longitude = position.coords.longitude;

    status.textContent = '';
    mapLink.href = `https://www.openstreetmap.org/#map=18/${latitude}/${longitude}`;
    mapLink.textContent = `Latitude: ${latitude} °, Longitude: ${longitude} °`;
  }

  function error() {
    status.textContent = 'Unable to retrieve your location';
  }

  if(!navigator.geolocation) {
    status.textContent = 'Geolocation is not supported by your browser';
  } else {
    status.textContent = 'Locating…';
    navigator.geolocation.getCurrentPosition(success, error);
  }

}

document.querySelector('#find-me').addEventListener('click', geoFindMe);

Result

Specifications

Specification Status Comment
Geolocation API Recommendation

Browser compatibility

DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
GeolocationChrome Full support 5Edge Full support 12Firefox Full support 3.5
Notes
Full support 3.5
Notes
Notes GPSD (GPS daemon) support added in Firefox 3.6. WiFi-based location is provided by Google (privacy) or a custom provider (MLS instructions).
IE Full support 9Opera Full support 10.6Safari Full support 5WebView Android Full support ≤37Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 11Safari iOS Full support 5Samsung Internet Android Full support 1.0
clearWatchChrome Full support 5Edge Full support 12Firefox Full support 3.5IE Full support 9Opera Full support 10.6Safari Full support 5WebView Android Full support ≤37Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 11Safari iOS Full support 5Samsung Internet Android Full support 1.0
getCurrentPositionChrome Full support 5Edge Full support 12Firefox Full support 3.5IE Full support 9Opera Full support 10.6Safari Full support 5WebView Android Full support ≤37Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 11Safari iOS Full support 5Samsung Internet Android Full support 1.0
Secure context requiredChrome Full support 50Edge Full support ≤79Firefox Full support 55IE No support NoOpera Full support 37Safari Full support YesWebView Android Full support 51
Notes
Full support 51
Notes
Notes Secure context is only required for applications targeting Android Nougat (7) and higher. See bug 603574.
Chrome Android Full support 50Firefox Android Full support 55Opera Android Full support 37Safari iOS Full support YesSamsung Internet Android Full support 5.0
watchPositionChrome Full support 5Edge Full support 12Firefox Full support 3.5IE Full support 9Opera Full support 10.6Safari Full support 5WebView Android Full support ≤37Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 11Safari iOS Full support 5Samsung Internet Android Full support 1.0

Legend

Full support
Full support
No support
No support
See implementation notes.
See implementation notes.

Availability

As WiFi-based locationing is often provided by Google, the vanilla Geolocation API may be unavailable in China. You may use local third-party providers such as Baidu, Autonavi, or Tencent. These services use the user's IP address and/or a local app to provide enhanced positioning.

See also