Getting Started¶

Ellipsoid Support¶

All distance, bearing, destination, interpolation, and spatial query functions accept an optional ellipsoid parameter. By default, WGS-84 is used.

from geodistpy import geodist, ELLIPSOIDS

# Use a named ellipsoid
d = geodist((52.52, 13.405), (48.8566, 2.3522), metric="km", ellipsoid="GRS-80")

# Use a custom (a, f) tuple
d = geodist((52.52, 13.405), (48.8566, 2.3522), ellipsoid=(6378137.0, 1/298.257223563))

# See all available ellipsoids
print(ELLIPSOIDS.keys())
# dict_keys(['WGS-84', 'GRS-80', 'Airy (1830)', 'Intl 1924', 'Clarke (1880)', 'GRS-67'])

Supported named ellipsoids: WGS-84 (default), GRS-80, Airy (1830), Intl 1924, Clarke (1880), GRS-67. You can also pass any (semi_major_axis, flattening) tuple.

Installation¶

You can install the geodistpy package using pip:

pip install geodistpy

Optional extras for pandas and GeoPandas (DataFrame/GeoDataFrame support):

pip install geodistpy[pandas]       # use DataFrames with geodist_to_many, geodesic_knn, point_in_radius
pip install geodistpy[geopandas]    # use GeoDataFrames (includes pandas)

Quick Start Guide¶

The quickest way to start using the geodistpy package is to calculate the distance between two geographical coordinates. Here's how you can do it:

from geodistpy import geodist

# Define two coordinates in (latitude, longitude) format
coord1 = (52.5200, 13.4050)  # Berlin, Germany
coord2 = (48.8566, 2.3522)   # Paris, France

# Calculate the distance between the two coordinates in kilometers
distance_km = geodist(coord1, coord2, metric='km')
print(f"Distance between Berlin and Paris: {distance_km} kilometers")

Beyond Distance: Bearing, Destination, and Spatial Queries¶

geodistpy goes beyond simple distance calculations. Here are a few more things you can do right away:

from geodistpy import bearing, destination, midpoint, interpolate, geodist_to_many, point_in_radius, geodesic_knn

berlin = (52.5200, 13.4050)
paris  = (48.8566, 2.3522)
cities = [(48.8566, 2.3522), (51.5074, -0.1278), (40.7128, -74.006)]

# Bearing: initial direction from Berlin to Paris
print(f"Bearing: {bearing(berlin, paris):.2f}°")

# Destination: where do you end up travelling 500 km east from Berlin?
print(f"Destination: {destination(berlin, 90.0, 500, metric='km')}")

# Midpoint along the geodesic
print(f"Midpoint: {midpoint(berlin, paris)}")

# 3 evenly-spaced waypoints between Berlin and Paris
print(f"Waypoints: {interpolate(berlin, paris, n_points=3)}")

# One-to-many: distance from Berlin to each city
dists = geodist_to_many(berlin, cities, metric='km')
print(f"Distances to cities: {dists.round(1)} km")

# Which of these cities are within 1000 km of Berlin?
idx, dists = point_in_radius(berlin, cities, 1000, metric='km')
print(f"Within 1000 km: {idx}")

# 2 nearest cities to Berlin
idx, dists = geodesic_knn(berlin, cities, k=2, metric='km')
print(f"2 nearest: {idx}, distances: {dists.round(1)} km")

For pandas DataFrames and the after-geocoding workflow, see Pandas & GeoPandas Support. For full API details, see the API Reference.