sphere-knn
v1.4.0
Published
search for k nearest neighbors on a sphere
Downloads
5,293
Readme
sphere-knn
sphere-knn
is a Node.JS module that provides fast nearest-neighbor lookups on
a sphere. This is useful if, for example, you have a database of geographic
points (latitude, longitude) and want to swiftly look up which of those points
are near a given latitude, longitude pair. It came out of a need to do such
lookups in the Dark Sky API, but all
existing libraries either threw scary runtime flags, were too slow, broke at
the International Date Line, or didn't have tests.
So anyway, this one is well-tested and works correctly regardless of where on the earth things are located. It's been in production use at Dark Sky since Oct 2012.
Usage
To install:
npm install sphere-knn
To use:
var sphereKnn = require("sphere-knn"),
lookup = sphereKnn([
/* This array needs to be full of objects that have latitudes and
* longitudes. Accepted property names are "lat", "latitude", "lon",
* "lng", "long", "longitude". */
{lat: ..., lon: ...},
/* You can also use an array. */
[my_lat, my_lon],
...
])
var points = lookup(someLatitude, someLongitude, maxResults, maxDistance)
The points
array consists of objects that were in the array passed to
sphereKnn()
, ordered from nearest to furthest. The maxResults
value is the
maximum size of the returned array, and is mandatory. (Often, you'll just want
it set to 1, but there are use-cases for more points.) The maxDistance
value
is the maximum distance away we should look up for in meters. This is handy if
you want to find, say, any points within 200 kilometers of a given point.
maxDistance
is optional and defaults to Infinity. (Please note that since our
backing earth model is a sphere, all distances given to this function are
approximate. If it matters that much to you, add a few meters of padding and
check the results with some very accurate (and complex) distance function.)
License
To the extend possible by law, The Dark Sky Company, LLC has waived all copyright and related or neighboring rights to this library.