Geolocation

Provides a consistent API to the geolocation on all platforms.

Estimate geolocation data from the device and use helper functions to create and measure the distance between positions on the earth's surface at specified latitudes and longitudes.

The LatLon class provides helper functions for computing quantities related to Geolocation.

Note: Due to privacy features in some browsers, the Geolocation API may be restricted or altogether fail to report values.

Example

var geolocation = new MotionStack.Geolocation({
  enableHighAccuracy: true,
  maximumAge: 700,
  timeout: 2500,
  pacemaker: true
});

geolocation.start(function(e) {
  // log a single reading and
  // then stop receiving updates
  console.log(e.lat, e.lon);
  geolocation.stop();
});

Constructor

new MotionStack.Geolocation([options])

Create a new instance of the Geolocation class.

Argument Type Description
options Object Options to pass in for the new Geolocation instance (optional)

  • enableHighAccuracy {Boolean}
  • If possible, report the most accurate results. Note this might increase response time and increase power usage.


    Default: false

  • maximumAge {Number}
  • The maximum amount of time in milliseconds to save and return a cached position estimate.


    Default: 700

  • timeout {Number}
  • The maximum amount of time in milliseconds allowed to return a position estimate. After the timeout, the request for position is re-dispatched.


    Default: 2500

  • pacemaker {Boolean}
  • Require Geolocation to update the value based on options.timeout


    Default: true

  • fireOnAnimationFrame {Boolean}
  • Only emit the latest event within requestAnimationFrame intervals.


    Default: false

var geolocation = new MotionStack.Geolocation({
  enableHighAccuracy: true,
  maximumAge: 700,
  timeout: 2500,
  pacemaker: true
});

Static Methods

isSupported()

Returns a Boolean value describing whether the device has GPS capability.

MotionStack.Geolocation.isSupported(); // true or false

currentPosition(callback, options)

Get the current GPS position of the user. This method can be called before or while the start method is running. This method is for usage when only a single position is needed.

Argument Type Description
callback Function Callback function that receives a LatLon object as an argument

  • function(latLon)
  • latLon {Object}
    An instance of the LatLon class
options Object Options to pass in for the new Geolocation instance (optional)

  • enableHighAccuracy {Boolean}
  • If possible, report the most accurate results. Note this might increase response time and increase power usage.


    Default: false

  • maximumAge {Number}
  • The maximum amount of time in milliseconds to save and return a cached position estimate.


    Default: 700

  • timeout {Number}
  • The maximum amount of time in milliseconds allowed to return a position estimate. After the timeout, the request for position is re-dispatched.


    Default: 2500

  • pacemaker {Boolean}
  • Require Geolocation to update the value based on options.timeout


    Default: true

var position = MotionStack.Geolocation.currentPosition(
  function(e) {
    console.log(e.lat, e.lon);
  },
  {
    enableHighAccuracy: true,
    maximumAge: 700,
    timeout: 2500,
    pacemaker: true
  }
);

distanceBetween(origin, destination, [precision])

Returns the distance (in kilometers) from the origin to the destination.

Argument Type Description
origin Object An object representing the latitude and longitude of the origin.

  • lat {Number}
  • Earth-based latitude of the destination point (degrees)
  • lon {Number}
  • Earth-based longitude of the destination point (degrees)
destination Object An object representing the latitude and longitude of the destination.

  • lat {Number}
  • Earth-based latitude of the destination point (degrees)
  • lon {Number}
  • Earth-based longitude of the destination point (degrees)
precision Number Number of significant digits to use for returned value.
Default: 4
// How far to the Googleplex from the Adtile office?
var adtile = { lat: 32.914, lon: -117.235};
var googleplex = { lat: 37.422, lon: -122.084 };

var distance = MotionStack.Geolocation.distanceBetween(adtile, googleplex);
console.log(distance + "km");

bearingBetween(origin, destination)

Returns the bearing (in degrees) from the origin to the destination.

Argument Type Description
origin Object An object representing the latitude and longitude of the origin.

  • lat {Number}
  • Earth-based latitude of the destination point (degrees)
  • lon {Number}
  • Earth-based longitude of the destination point (degrees)
destination Object An object representing the latitude and longitude of the destination.

  • lat {Number}
  • Earth-based latitude of the destination point (degrees)
  • lon {Number}
  • Earth-based longitude of the destination point (degrees)
// Which direction is the Googleplex from the Adtile office?
var adtile = { lat: 32.914, lon: -117.235};
var googleplex = { lat: 37.422, lon: -122.084 };

var bearing = MotionStack.Geolocation.bearingBetween(adtile, googleplex);
console.log(bearing + " degrees");

Instance Methods

start(callback, [context])

Start receiving geolocation updates.

Argument Type Description
callback Function Callback function that receives a LatLon object as an argument

  • function(latLon)
  • latLon {Object}
    An instance of the LatLon class
context Object Context in which to invoke the callback (optional).
geolocation.start(function(e) {
  console.log(e.lat, e.lon);
});

stop()

Stop geolocation updates.

geolocation.stop();

Source

src/interfaces/Geolocation.js