# sphere-knn

> search for k nearest neighbors on a sphere

Latest version **1.4.0** (published 2018-03-13) · 0 weekly downloads

## Install

```sh
npm install sphere-knn
pnpm add sphere-knn
yarn add sphere-knn
bun add sphere-knn
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2018-03-13 |
| First published | 2012-11-20 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6.0.0 |
| Dependencies | 0 |
| Unpacked size | 17.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 123 |
| Author | The Dark Sky Company |
| Maintainers | darkskybot, ironwallaby, jeffbyrnes |
| Keywords | kd-tree, nearest neighbor |

## Links

- npm: https://www.npmjs.com/package/sphere-knn
- Repository: https://github.com/darkskyapp/sphere-knn
- Homepage: https://github.com/darkskyapp/sphere-knn#readme
- Issues: https://github.com/darkskyapp/sphere-knn/issues
- npm.io page: https://npm.io/package/sphere-knn

## Recent versions

- 1.4.0 (latest) — 2018-03-13
- 1.3.1 — 2016-11-16
- 1.3.0 — 2016-10-05
- 1.2.1 — 2013-03-14
- 1.2.0 — 2012-11-20

## 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](http://developer.darkskyapp.com/), 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][cc0] to this library.

[cc0]: http://creativecommons.org/publicdomain/zero/1.0/

---
_Source: https://npm.io/package/sphere-knn · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._