Secure contextThis 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:
Geolocation.getCurrentPosition()
: Retrieves the device's current location.Geolocation.watchPosition()
: Registers a handler function that will be called automatically each time the position of the device changes, returning the updated location.
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 insideGeolocation
, inside a success callback, and contains a timestamp plus aGeolocationCoordinates
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 insideGeolocation
, 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()
andGeolocation.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.
body {
padding: 20px;
background-color:#ffffc9
}
button {
margin: .5rem 0;
}
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
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Geolocation
|
Chrome
Full support 5 |
Edge
Full support 12 |
Firefox Full support 3.5 Full support 3.5 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 9 |
Opera
Full support 10.6 |
Safari
Full support 5 |
WebView Android
Full support ≤37 |
Chrome Android
Full support 18 |
Firefox Android
Full support 4 |
Opera Android
Full support 11 |
Safari iOS
Full support 5 |
Samsung Internet Android
Full support 1.0 |
clearWatch
|
Chrome
Full support 5 |
Edge
Full support 12 |
Firefox
Full support 3.5 |
IE
Full support 9 |
Opera
Full support 10.6 |
Safari
Full support 5 |
WebView Android
Full support ≤37 |
Chrome Android
Full support 18 |
Firefox Android
Full support 4 |
Opera Android
Full support 11 |
Safari iOS
Full support 5 |
Samsung Internet Android
Full support 1.0 |
getCurrentPosition
|
Chrome
Full support 5 |
Edge
Full support 12 |
Firefox
Full support 3.5 |
IE
Full support 9 |
Opera
Full support 10.6 |
Safari
Full support 5 |
WebView Android
Full support ≤37 |
Chrome Android
Full support 18 |
Firefox Android
Full support 4 |
Opera Android
Full support 11 |
Safari iOS
Full support 5 |
Samsung Internet Android
Full support 1.0 |
Secure context required | Chrome
Full support 50 |
Edge
Full support ≤79 |
Firefox
Full support 55 |
IE
No support No |
Opera
Full support 37 |
Safari
Full support Yes |
WebView Android Full support 51 Full support 51 Notes' Secure context is only required for applications targeting Android Nougat (7) and higher. See bug 603574. |
Chrome Android
Full support 50 |
Firefox Android
Full support 55 |
Opera Android
Full support 37 |
Safari iOS
Full support Yes |
Samsung Internet Android
Full support 5.0 |
watchPosition
|
Chrome
Full support 5 |
Edge
Full support 12 |
Firefox
Full support 3.5 |
IE
Full support 9 |
Opera
Full support 10.6 |
Safari
Full support 5 |
WebView Android
Full support ≤37 |
Chrome Android
Full support 18 |
Firefox Android
Full support 4 |
Opera Android
Full support 11 |
Safari iOS
Full support 5 |
Samsung 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
Geolocation API by Mozilla Contributors is licensed under CC-BY-SA 2.5.