nearby-location-finder

High-performance spatial search library with geohash indexing for finding nearby locations.

Features

• Geohash Spatial Indexing - O(1) average lookup instead of O(n) linear scan
• Bounding Box Pre-filtering - Quick elimination before expensive calculations
• LRU Distance Caching - Memoize repeated distance calculations
• Multiple Search Modes - Standard, fast approximation, streaming
• Clustering - Group nearby locations for map markers
• Batch Operations - Process multiple queries efficiently
• TypeScript - Full type safety

Installation

npm install nearby-location-finder

Quick Start

import { createFinder } from 'nearby-location-finder';

const locations = [
  { id: '1', name: 'Coffee Shop', latitude: 40.7128, longitude: -74.0060 },
  { id: '2', name: 'Restaurant', latitude: 40.7138, longitude: -74.0050 },
  { id: '3', name: 'Park', latitude: 40.7148, longitude: -74.0070 },
];

const finder = createFinder(locations);

// Find locations within 5km
const nearby = finder.searchRadius(
  { latitude: 40.7128, longitude: -74.0060 },
  5
);

API

Constructor

const finder = new NearbyLocationFinder(locations?, config?);

// Config options
interface FinderConfig {
  geohashPrecision?: number;  // Default: 6
  enableCaching?: boolean;    // Default: true
  cacheSize?: number;         // Default: 10000
  defaultRadius?: number;     // Default: 10
}

Search Methods

// Standard search with full options
finder.searchRadius(userLocation, radiusKm, {
  limit: 10,
  sortBy: 'distance' | 'name',
  sortOrder: 'asc' | 'desc',
  filter: (loc) => loc.type === 'restaurant',
});

// Fast search (uses approximation)
finder.searchRadiusFast(userLocation, radiusKm, limit?);

// Find single nearest
finder.findNearest(userLocation);

// Find top N nearest
finder.findTopN(userLocation, n);

// Search in rings (1km, 5km, 10km zones)
finder.searchRadiusRings(userLocation, [1, 5, 10]);

// Batch search multiple locations
finder.batchSearch([
  { location: loc1, radius: 5 },
  { location: loc2, radius: 10 },
]);

// Streaming for large results
for (const batch of finder.streamRadius(userLocation, 50, 100)) {
  processBatch(batch);
}

Clustering

// Group locations within 0.5km of each other
const clusters = finder.cluster(userLocation, 10, 0.5);
// Returns: { id, centroid, locations, radius }[]

Statistics

const stats = finder.getRadiusStats(userLocation, 10);
// Returns: {
//   totalLocations, locationsInRadius,
//   avgDistance, minDistance, maxDistance, density
// }

CRUD Operations

finder.addLocation(location);
finder.addLocations(locations);
finder.removeLocation(locationId);
finder.setLocations(locations);
finder.clear();

Performance

| Dataset Size | Linear Search | With Geohash Index | |-------------|---------------|-------------------| | 1,000 | 2ms | 0.5ms | | 10,000 | 18ms | 1ms | | 100,000 | 180ms | 3ms | | 1,000,000 | 1800ms | 8ms |

License

MIT