distance-calculator

距離計算ツール

さまざまな方法で地理的な距離を計算し、近くの場所を検索します。

特長

• 2点間の距離：ハバースイン、ビンセンティ、球面距離
• 距離行列：すべての組み合わせの距離
• 最近傍検索：最も近いN個の地点を検索
• 半径検索：指定した距離内のすべての地点を検索
• バッチ処理：CSVファイルを処理
• 複数の単位：km、マイル、メートル、海里

クイックスタート

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 の使い方

# 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 リファレンス

DistanceCalculator クラス

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)

距離計算方法

ハバースイン（デフォルト）

• 地球を球体と仮定した大圏距離
• ほとんどの用途で高速かつ正確です
• 誤差：最大約0.5％

ビンセンティ

• より正確で、地球の楕円体形状を考慮します
• やや低速です
• 誤差：約0.5mm

calc = DistanceCalculator(method="vincenty")

単位

単位	説明
km	キロメートル（デフォルト）
miles	マイル
m	メートル
nm	海里
ft	フィート

calc = DistanceCalculator(unit="miles")
# Or convert after
dist_km = calc.distance(p1, p2)
dist_miles = calc.convert(dist_km, "km", "miles")

ワークフローの例

最寄りの店舗を検索

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")

配達エリアの確認

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")

経路検索用の距離行列

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")

出力形式

距離の結果

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

最近傍地点の結果

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

依存関係

• geopy>=2.4.0