Distance Calculator

Calculate geographic distances and find nearby locations using various methods.

Features Point-to-Point Distance: Haversine, Vincenty, great circle Matrix Distances: All pairs distances Nearest Neighbors: Find closest N points Radius Search: Find all points within distance Batch Processing: Process CSV files Multiple Units: km, miles, meters, nautical miles Quick Start from distance_calc import DistanceCalculator

calc = DistanceCalculator()

Simple distance

dist = calc.distance( (40.7128, -74.0060), # New York (34.0522, -118.2437) # Los Angeles ) print(f"Distance: {dist:.2f} km")

Find nearest points

nearest = calc.find_nearest( origin=(40.7128, -74.0060), points=store_locations, n=5 )

CLI Usage

Distance between two points

python distance_calc.py --from "40.7128,-74.0060" --to "34.0522,-118.2437"

Find nearest from CSV

python distance_calc.py --origin "40.7128,-74.0060" --input stores.csv --nearest 5

Points within radius

python distance_calc.py --origin "40.7128,-74.0060" --input stores.csv --radius 50

Distance matrix

python distance_calc.py --input locations.csv --matrix --output distances.csv

Different units

python distance_calc.py --from "40.7128,-74.0060" --to "34.0522,-118.2437" --unit miles

API Reference DistanceCalculator Class class DistanceCalculator: def init(self, unit: str = "km", method: str = "haversine")

# Point-to-point
def distance(self, point1: tuple, point2: tuple) -> float
def distance_with_details(self, point1: tuple, point2: tuple) -> dict

# Batch operations
def distance_matrix(self, points: list) -> list
def distances_from_origin(self, origin: tuple, points: list) -> list

# Search
def find_nearest(self, origin: tuple, points: list, n: int = 1) -> list
def find_within_radius(self, origin: tuple, points: list, radius: float) -> list

# File operations
def from_csv(self, filepath: str, lat_col: str, lon_col: str) -> list
def matrix_to_csv(self, matrix: list, labels: list, output: str)

Distance Methods Haversine (Default) Great circle distance assuming spherical Earth Fast and accurate for most purposes Error: ~0.5% max Vincenty More accurate, accounts for Earth's ellipsoid shape Slightly slower Error: ~0.5mm calc = DistanceCalculator(method="vincenty")

Units Unit Description km Kilometers (default) miles Miles m Meters nm Nautical miles ft Feet calc = DistanceCalculator(unit="miles")

Or convert after

dist_km = calc.distance(p1, p2) dist_miles = calc.convert(dist_km, "km", "miles")

Example Workflows Find Nearest Stores calc = DistanceCalculator(unit="miles") stores = calc.from_csv("stores.csv", "lat", "lon")

customer = (40.7128, -74.0060) nearest = calc.find_nearest(customer, stores, n=3)

for store in nearest: print(f"{store['name']}: {store['distance']:.1f} miles")

Delivery Zone Check calc = DistanceCalculator(unit="km") warehouse = (40.7128, -74.0060) delivery_radius = 50 # km

customers = calc.from_csv("customers.csv", "lat", "lon") in_zone = calc.find_within_radius(warehouse, customers, delivery_radius)

print(f"{len(in_zone)} customers in delivery zone")

Distance Matrix for Routing calc = DistanceCalculator() stops = [ (40.7128, -74.0060), (40.7589, -73.9851), (40.7484, -73.9857), (40.7527, -73.9772) ]

matrix = calc.distance_matrix(stops) calc.matrix_to_csv(matrix, ["HQ", "Store1", "Store2", "Store3"], "distances.csv")

Output Formats Distance Result { "distance": 3935.75, "unit": "km", "from": {"lat": 40.7128, "lon": -74.0060}, "to": {"lat": 34.0522, "lon": -118.2437}, "method": "haversine" }

Nearest Points Result [ {"point": (lat, lon), "distance": 5.2, "data": {...}}, {"point": (lat, lon), "distance": 8.1, "data": {...}}, ]

Dependencies geopy>=2.4.0