The Geolocation API

Posted by Ryan Evans on November 2, 2019

The Geolocation API allows the user to provide their location to an application if they wish to. The Geolocation API is provided through the navigator.geolocation object. If the navigator.geolocation object exists, then Geolocation services are available. Here’s a simple example to test if geolocation services are available, provided by MDN:

if ("geolocation" in navigator) {
  /* geolocation is available */
} else {
  /* geolocation IS NOT available */
}


The Geolocation object has three useful methods:

  • getCurrentPosition() - does exactly as the name implies, getting the current position
  • watchPosition() - does what the name implies as well, continually tracking position
  • clearWatch() - terminates the continuous tracking started by watchPosition()


getCurrentPosition() and watchPosition() require a callback function to handle the Position object it receives upon a succesful location request. They both also have an optional second parameter for a callback function to handle the PositionError object if the request fails.

The clearWatch() method takes one parameter, which is the watchID , an ID number that was returned from the watchPosition() method.

Here’s an example of usage from MDN that only handles a successful request:

navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
});


This example from Crate.io checks that the browser supports geolocation, and then calls the getCurrentPosition() method which either passes a Position object to the onGeolocateSuccess() callback function, or the PositionError object to the onGeolocateError() callback function:

function geolocate() {
  if (window.navigator && window.navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(onGeolocateSuccess, onGeolocateError);
  }
}


The getCurrentPosition() and watchPosition() methods will also take an additional third PositionOptions object with three properties (it doesn’t inherit any properties):

  • enableHighAccuracy - a boolean which is set to false by default in order to load faster (and use less power), if true the device will provide more accurate position information if it can
  • timeOut - which is the maximum amount of time (in ms) that the device can take to return the position (the default is infinity)
  • maximumAge - which is how old a cached position can be (the default is 0, meaning that the device isn’t allowed to use a cached position)


Remember that using the Geolocation API will prompt users to either ‘block’ or ‘allow’ geolocation services being shared with your application. It is also only available in a secure context requiring an https connection.

Resources: