---

name: distance-calculator description: Calculate distances between geographic coordinates, find nearby points, and compute travel distances. Use for logistics, delivery routing, or location analysis.

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

Copyfrom 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

Copy# 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

Copyclass 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

Copycalc = DistanceCalculator(method="vincenty")

Units

Copycalc = 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

Copycalc = 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

Copycalc = 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

Copycalc = 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

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

Nearest Points Result

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

Dependencies

• geopy>=2.4.0