This site is mobile accessible. Press the "Tap Here" button to use a different font-size.

Smartphone icons created by Freepik - Flaticon

16.7 Web Geolocation API

Locate the User's Position

The HTML Geolocation API is used to get the geographical position of a user.
Since this can compromise privacy, the position is not available unless the user approves it.
Note
Geolocation is most accurate for devices with GPS, like smartphones.

Browser Support

The Geolocation API is supported in all browsers:


Yes	Yes	Yes	Yes	Yes

Note
The Geolocation API will only work on secure contexts such as HTTPS.
If your site is hosted on a non-secure origin (such as HTTP) the requests to get the users location will no longer function.

Using the Geolocation API

The getCurrentPosition() method is used to return the user's position.
The example below returns the latitude and longitude of the user's position:

Example 1: JS Geolocation API

<script>
const x = document.getElementById("demo");
function getLocation() {
  if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(showPosition);
  } else {
    x.innerHTML = "Geolocation is not supported by this browser.";
  }
}

function showPosition(position) {
  x.innerHTML = "Latitude: " + position.coords.latitude +
  "
Longitude: " + position.coords.longitude;
}
</script>

Example explained:
- Check if Geolocation is supported
- If supported, run the getCurrentPosition() method. If not, display a message to the user
- If the getCurrentPosition() method is successful, it returns a coordinates object to the function specified in the parameter (showPosition)
- The showPosition() function outputs the Latitude and Longitude
The example above is a very basic Geolocation script, with no error handling.

Handling Errors and Rejections

The second parameter of the getCurrentPosition() method is used to handle errors. It specifies a function to run if it fails to get the user's location:

Example 2: JS Geolocation API part 2

function showError(error) {
  switch(error.code) {
    case error.PERMISSION_DENIED:
      x.innerHTML = "User denied the request for Geolocation."
      break;
    case error.POSITION_UNAVAILABLE:
      x.innerHTML = "Location information is unavailable."
      break;
    case error.TIMEOUT:
      x.innerHTML = "The request to get user location timed out."
      break;
    case error.UNKNOWN_ERROR:
      x.innerHTML = "An unknown error occurred."
      break;
  }
}

Displaying the Result in a Map

To display the result in a map, you need access to a map service, like Google Maps.
In the example below, the returned latitude and longitude is used to show the location in a Google Map (using a static image):

Example

function showPosition(position) {
  let latlon = position.coords.latitude + "," + position.coords.longitude;

  let img_url = "https://maps.googleapis.com/maps/api/staticmap?center=
  "+latlon+"&zoom=14&size=400x300&sensor=false&key=YOUR_KEY";

  document.getElementById("mapholder").innerHTML = "<img src='"+img_url+"'>";
}

Location-specific Information

This page has demonstrated how to show a user's position on a map.
Geolocation is also very useful for location-specific information, like:
- Up-to-date local information
- Showing Points-of-interest near the user
- Turn-by-turn navigation (GPS)

The getCurrentPosition() Method - Return Data

The getCurrentPosition() method returns an object on success. The latitude, longitude and accuracy properties are always returned. The other properties are returned if available:

Property	Returns
coords.latitude	The latitude as a decimal number (always returned)
coords.longitude	The longitude as a decimal number (always returned)
coords.accuracy	The accuracy of position (always returned)
coords.altitude	The altitude in meters above the mean sea level (returned if available)
coords.altitudeAccuracy	The altitude accuracy of position (returned if available)
coords.heading	The heading as degrees clockwise from North (returned if available)
coords.speed	The speed in meters per second (returned if available)
timestamp	The date/time of the response (returned if available)

Geolocation Object - Other interesting Methods

The Geolocation object also has other interesting methods:
- watchPosition() - Returns the current position of the user and continues to return updated position as the user moves (like the GPS in a car).
- clearWatch() - Stops the watchPosition() method.
The example below shows the watchPosition() method. You need an accurate GPS device to test this (like smartphone):

Example 3: JS Geolocation API part 3

<script>
const x = document.getElementById("demo");
function getLocation() {
  if (navigator.geolocation) {
    navigator.geolocation.watchPosition(showPosition);
  } else {
    x.innerHTML = "Geolocation is not supported by this browser.";
  }
}
function showPosition(position) {
  x.innerHTML = "Latitude: " + position.coords.latitude +
  "<br>Longitude: " + position.coords.longitude;
}
</script>

JavaScript Fundamentals course home
Module 16. JS Web APIs

Navigate this module

Eventually the navigation links, above, will be replaced by these << (previous) and >> (next) buttons below.

JavaScript icons used in the buttons provided by ICONS8.COM. Smartphone icons created by Freepik - Flaticon

Example files created in this module:
JS Web API - Geolocation API JS Web Storage API Web Storage API - The sessionStorage Object JS Web Worker API - Counting Numbers JS Web Fetch API part 1 JS Web Fetch API part 2 JS Web Fetch API part 3 JS Geolocation API part 1 JS Geolocation API part 2 JS Geolocation API part 3