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.
The geolocation object
The Geolocation API is published through the navigator.geolocation
object.
If the object exists, geolocation services are available. You can test for the presence of geolocation thusly:
if ("geolocation" in navigator) { /* geolocation is available */ } else { /* geolocation IS NOT available */ }
Note: On Firefox 24 and older versions, "geolocation" in navigator
always returned true
even if the API was disabled. This has been fixed with Firefox 25 to comply with the spec. (bug 884921).
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, the defined callback function is executed. You can optionally provide a second callback function to be executed if an error occurs. A third, optional, parameter is an options object where you can set the maximum age of the position returned, the time to wait for a request, and if you want high accuracy for the position.
Note: By default, getCurrentPosition()
tries to answer as fast as possible with a low accuracy result. It is useful if you need a quick answer regardless of the accuracy. Devices with a GPS, for example, can take a minute or more to get a GPS fix, so less accurate data (IP location or wifi) may be returned to getCurrentPosition()
.
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 the position data changes (either by device movement or if more accurate geo information arrives), you can set up a callback function that is called with that updated position information. This is done using the watchPosition()
function, which has the same input parameters as getCurrentPosition()
. The callback function is called multiple times, allowing the browser to either update your location as you move, or provide a more accurate location as different techniques are used to geolocate you. The error callback function, which is optional just as it is for getCurrentPosition()
, can be called repeatedly.
Note: You can use watchPosition()
without an initial getCurrentPosition()
call.
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);
Fine tuning response
Both getCurrentPosition()
and watchPosition()
accept a success callback, an optional error callback, and an optional PositionOptions object.
A call to watchPosition
could look like:
function geo_success(position) { do_something(position.coords.latitude, position.coords.longitude); } function geo_error() { alert("Sorry, no position available."); } var geo_options = { enableHighAccuracy: true, maximumAge : 30000, timeout : 27000 }; var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, geo_options);
Describing a position
The user's location is described using a Position
object referencing a Coordinates
object.
Handling errors
The error callback function, if provided when calling getCurrentPosition()
or watchPosition()
, expects a PositionError object as its first parameter.
function errorCallback(error) { alert('ERROR(' + error.code + '): ' + error.message); };
Geolocation Live Example
body { padding: 20px; background-color:#ffffc9 } button { margin: .5rem 0; }
HTML Content
<button id = "find-me">Show my location</button><br/> <p id = "status"></p> <a id = "map-link" target="_blank"></a>
JavaScript Content
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);
Live Result
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Geolocation | Chrome Full support 5 | Edge Full support 12 | Firefox
Full support
3.5
| IE Full support 9 | Opera
Full support
16
| Safari Full support 5 | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 4 | Opera Android
Full support
16
| Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
clearWatch | Chrome Full support 5 | Edge Full support 12 | Firefox Full support 3.5 | IE Full support 9 | Opera
Full support
16
| Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 4 | Opera Android
Full support
16
| Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
getCurrentPosition | Chrome Full support 5 | Edge Full support 12 | Firefox Full support 3.5 | IE Full support 9 | Opera
Full support
16
| Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 4 | Opera Android
Full support
16
| Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
Secure context required | Chrome Full support 50 | Edge ? | Firefox Full support 55 | IE No support No | Opera Full support 37 | Safari Full support Yes | WebView Android
Full support
51
| Chrome Android Full support 50 | Firefox Android Full support 55 | Opera Android Full support 37 | Safari iOS Full support Yes | Samsung Internet Android ? |
watchPosition | Chrome Full support 5 | Edge Full support 12 | Firefox Full support 3.5 | IE Full support 9 | Opera
Full support
16
| Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support 18 | Firefox Android Full support 4 | Opera Android
Full support
16
| Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- 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.