README.md

random-location

random-location gets you random coordinates within a circle (or on a circumference) given a center point and radius. We use it to stress test our geohash based services. It works anywhere JavaScript runs.

web example | react-native example

Installation

Using npm:

$ npm install --save random-location

Then use as you would anything else:

// Using ES6 modules
import randomLocation from 'random-location'

// Using CommonJS modules
const randomLocation = require('random-location')

The UMD build is also available on unpkg:

<script src="https://unpkg.com/random-location/dist/randomLocation.umd.js"></script>

API

randomLocation.randomCirclePoint(...)

Outputs a Point ( { latitude: ..., longitude: ... }) of random coordinates within a circle.

Function definition:

const randomCirclePoint = (centerPoint, radius, randomFn = Math.random) => { ... }

Where:

• centerPoint required An object with a latitude and longitude fields.
• radius required The maximum distance (meters) from centerPoint.
• randomFn optional A random function. Output is >=0 and <=1. Allows usage of seeded random number generators (see seedrandom) - more predictability when testing.

randomLocation.randomCircumferencePoint(...)

Outputs a Point ( { latitude: ..., longitude: ... }) of random coordinates on a circle's circumference.

Function definition:

const randomCircumferencePoint= (centerPoint, radius, randomFn = Math.random) => { ... }

Where:

• centerPoint required An object with a latitude and longitude fields.
• radius required The distance (meters) from centerPoint.
• randomFn optional A random function. Output is >=0 and <=1. Allows usage of seeded random number generators (see seedrandom) - more predictability when testing.

randomLocation.randomAnnulusPoint(...)

Outputs a Point ( { latitude: ..., longitude: ... }) of random coordinates in a region bounded by two concentric circles (annulus).

Function definition:

const randomCircumferencePoint= (centerPoint, radius, randomFn = Math.random) => { ... }

Where:

• centerPoint required An object with a latitude and longitude fields.
• innerRadius required The readius of the smaller circle.
• outerRadius required The readius of the larger circle.
• randomFn optional A random function. Output is >=0 and <=1. Allows usage of seeded random number generators (see seedrandom) - more predictability when testing.

Usage

Generating random coordinates within a circle

Lets say we'd like to get a random location that its distance from Twitter's HQ is at most 500 meters:

// Twitter HQ
const P = {
  latitude: 37.7768006,
  longitude: -122.4187928
}

const R = 500 // meters

const randomPoint = randomLocation.randomCirclePoint(P, R)

// randomPoint => { latitude: 37.77636619, longitude: -122.416575663 }

Generating random coordinates on a circle circumference

Lets say we'd like to get a random location that its distance from Twitter's HQ is exactly 700 meters:

// Twitter HQ
const P = {
  latitude: 37.7768006,
  longitude: -122.4187928
}

const R = 700 // meters

const randomPoint = randomLocation.randomCircumferencePoint(P, R)

// randomPoint => { latitude: 37.7828897, longitude: -122.4167713 }

Measure the distance between two points

// Eiffel Tower
const P1 = {
  latitude: 48.8583736,
  longitude: 2.2922926,
}

// Notre-Dame Cathedral
const P2 = {
  latitude: 48.8529717,
  longitude: 2.3477134,
}

// Prints True
console.log(Math.floor(randomLocation.distance(P1, P2)) === 4098)

Hacking

Clone. Install. Hack. Open a PR.

License

MIT.