distance-calculator
Calculate distances between geographic coordinates, find nearby points, and compute travel distances. Use for logistics, delivery routing, or location analysis.
When & Why to Use This Skill
This Claude skill provides a robust geographic calculation engine designed for high-precision distance computing and spatial analysis. It supports multiple mathematical models including Haversine and Vincenty formulas to ensure accuracy across various scales. Ideal for developers and analysts, it simplifies complex tasks like finding nearest neighbors, generating distance matrices, and processing batch coordinate data from CSV files, making it an essential tool for logistics, retail planning, and location-based service optimization.
Use Cases
- Logistics & Fleet Management: Calculate precise travel distances and distance matrices to optimize delivery routes and reduce operational costs.
- Retail Proximity Analysis: Identify the nearest store locations or service centers for customers using the 'find_nearest' and radius search features.
- Geofencing & Marketing: Filter large datasets to find all points of interest within a specific kilometer or mile radius for targeted local campaigns.
- Spatial Data Processing: Perform batch geographic audits by importing CSV files to calculate distances between thousands of coordinate pairs automatically.
- Real Estate & Urban Planning: Compute exact point-to-point distances to evaluate property proximity to key landmarks and infrastructure.
| 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
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