distance-calculator

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