geokdbush Documentation

To use geokdbush, you must first create a spatial index using kdbush. Once the index is finished, you can use geokdbush.around() to find the closest points to a specific longitude and latitude. The search accounts for Earth's curvature and date line wrapping.

Note that geokdbush works with the IDs returned by the kdbush index, which you can use to map back to your original data points.

import KDBush from 'kdbush';
import * as geokdbush from 'geokdbush';

const index = new KDBush(points.length);
for (const {lon, lat} of points) index.add(lon, lat);
index.finish();

const nearestIds = geokdbush.around(index, -119.7051, 34.4363, 1000);

const nearest = nearestIds.map(id => points[id]);

Returns an array of the closest points from a given location in order of increasing distance.

Parameters:

• index: A kdbush index.
• longitude: Query point longitude.
• latitude: Query point latitude.
• maxResults (optional): Maximum number of points to return. Defaults to Infinity.
• maxDistance (optional): Maximum distance in kilometers to search within. Defaults to Infinity.
• filterFn (optional): A function to filter the results with.

geokdbush.around(index, longitude, latitude[, maxResults, maxDistance, filterFn])

Returns the great circle distance between two locations in kilometers.

geokdbush.distance(longitude1, latitude1, longitude2, latitude2)

The around() function returns an array of the closest points from a given location, sorted by increasing distance. It performs spatial queries against a kdbush index.

Parameters:

• index: A kdbush index instance.
• lng: Query point longitude.
• lat: Query point latitude.
• maxResults (optional): Maximum number of points to return. Defaults to Infinity.
• maxDistance (optional): Maximum distance in kilometers to search within. Defaults to Infinity.
• predicate (optional): A function (item: number) => boolean used to filter results by their ID.

import { around } from 'geokdbush';

// Assuming 'index' is a valid kdbush index
const results = around(index, -74.006, 40.7128, 10, 5, (id) => id % 2 === 0);
// Returns up to 10 results within 5km, where the ID is even.

The distance() function calculates the great circle distance between two locations in kilometers using the Haversine formula.

import { distance } from 'geokdbush';

const km = distance(-74.006, 40.7128, -0.1278, 51.5074);
console.log(`Distance: ${km} km`);