Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
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.

JS Requesting the position safely

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Working with coordinates: distance between two points

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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 in new Promise((resolve, reject) => navigator.geolocation.getCurrentPosition(resolve, reject)).
  • Stop watches. A watchPosition() keeps running until you call clearWatch() or the page is closed. Clear it when the feature is no longer needed.
  • Accuracy is a promise, not a guarantee. Check coords.accuracy and 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.