JavaScript Reference ยท Browser and Web APIs
The Geolocation API
Reference for the JavaScript Geolocation API: getCurrentPosition(), watchPosition(), clearWatch(), coordinates, error codes, options and privacy rules.
The Geolocation API tells a page where the device is. You reach it through navigator.geolocation, which has three methods: getCurrentPosition() for a single reading, watchPosition() for updates as the device moves, and clearWatch() to stop them.
The browser always asks the user for permission first, and the page must be served from a secure context (HTTPS or localhost). The API is callback-based rather than promise-based, and the position can come from GPS, Wi-Fi networks or the IP address, so accuracy varies from a few meters to many kilometers.
navigator.geolocation.getCurrentPosition(onSuccess, onError, options);
Try it
Geolocation is not available inside the sandboxed editors on this site, so the first example shows the real call with its error handling, and the second works with a fixed fake position so you can see what to do with the numbers.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
navigator.geolocation.getCurrentPosition(success, error, options) const id = navigator.geolocation.watchPosition(success, error, options) navigator.geolocation.clearWatch(id)
| Name | Description |
|---|---|
success |
Called with a GeolocationPosition: its coords property and a timestamp. |
error |
Optional. Called with a GeolocationPositionError that has code (1, 2 or 3) and message. |
options.enableHighAccuracy |
A hint to prefer GPS-level accuracy. It can be slower and drain the battery. Default false. |
options.timeout |
Milliseconds to wait for a position before the error callback runs with code 3. Default is no limit. |
options.maximumAge |
Accept a cached position no older than this many milliseconds. Default 0. |
Return value: getCurrentPosition() returns undefined. watchPosition() returns a numeric ID for clearWatch().
The coords object has latitude, longitude (degrees), accuracy (meters), and often altitude, altitudeAccuracy, heading and speed, which can be null when the device cannot measure them.
Error codes: 1 permission denied, 2 position unavailable, 3 timeout.
Usage notes
- Ask at the right moment. Request the position after a user action such as pressing "Find stores near me", so the prompt makes sense. Pages that ask on load are often denied.
- Always pass an error callback. Denial is common, and your page should still work, for example with a manual city search.
- Callbacks, not promises. To use
await, wrap the call innew Promise((resolve, reject) => navigator.geolocation.getCurrentPosition(resolve, reject)). - Stop watches. A
watchPosition()keeps running until you callclearWatch()or the page is closed. Clear it when the feature is no longer needed. - Accuracy is a promise, not a guarantee. Check
coords.accuracyand be careful when it is large. - Privacy. Location is personal data. Collect only what you need, explain why, and avoid sending it to servers unnecessarily.
- Check permission without prompting using
navigator.permissions.query({ name: "geolocation" })where supported. - Iframes need
allow="geolocation"from the embedding page.
Browser support
The Geolocation API is supported in all current browsers on secure origins. Accuracy and caching behavior depend on the device and the browser.