Haversine

2.9.0 · active · verified Fri Apr 10

The `haversine` library (current version 2.9.0) calculates the great-circle distance between two points on Earth given their latitude and longitude, using the Haversine formula. It supports various units like kilometers, meters, miles, and nautical miles, and is commonly used in geospatial analysis and navigation. It maintains an active development status with regular updates.

Warnings

breaking The `miles` and `nautical_miles` boolean parameters were removed in version 1.0.0 (October 2018) and replaced by the unified `unit` parameter.
Fix: Replace `miles=True` or `nautical_miles=True` with `unit=Unit.MILES` or `unit=Unit.NAUTICAL_MILES` (or their string equivalents 'mi' / 'nmi').
gotcha Coordinates must be provided as `(latitude, longitude)` tuples. A common mistake is to reverse the order to `(longitude, latitude)`, leading to incorrect distance calculations.
Fix: Always ensure your point tuples are structured as `(latitude, longitude)`, for example `point1 = (lat1, lon1)`.
gotcha A `ValueError: math domain error` can occur if input latitude or longitude values are outside their valid ranges (latitude: [-90, 90], longitude: [-180, 180]) or due to floating-point precision issues near the poles or antipodal points.
Fix: Validate input coordinates to ensure they are within the valid ranges. Alternatively, use the `normalize=True` parameter in the `haversine` function to automatically clamp out-of-range values: `haversine(point1, point2, normalize=True)`.
deprecated Support for Python 2.7 was officially dropped in version 2.5.0.
Fix: Upgrade to Python 3.5 or newer. The `python_requires` is `>=3.5` for current versions.

Install

pip install haversine Install stable version

Imports

haversine
```
from haversine import haversine, Unit
```
Import `Unit` enum for specifying output distance units clearly. While string abbreviations work, `Unit` provides type safety and clarity.

Quickstart

Calculate the distance between two geographical points (Lyon and Paris) in kilometers, miles, and meters. Points are provided as (latitude, longitude) tuples.

from haversine import haversine, Unit

# Define points as (latitude, longitude) tuples
lyon = (45.7597, 4.8422)
paris = (48.8567, 2.3508)

# Calculate distance in kilometers (default)
distance_km = haversine(lyon, paris)
print(f"Distance between Lyon and Paris: {distance_km:.2f} km")

# Calculate distance in miles
distance_miles = haversine(lyon, paris, unit=Unit.MILES)
print(f"Distance between Lyon and Paris: {distance_miles:.2f} miles")

# Calculate distance in meters using string abbreviation
distance_m = haversine(lyon, paris, unit='m')
print(f"Distance between Lyon and Paris: {distance_m:.2f} meters")

view raw JSON →