haversine

library2.9.0pypypi✓ verified 30d ago

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.

data

pip install haversine

github ↗package ↗

INSTALL

IMPORT

SIG · HAVERSINE

haversine

datapythonv2.9.0

Install

1.7s avg

Import

13ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.014s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.012s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

haversine

✓ from haversine import haversine, Unit

✗ from haversine import haversine

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

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

Debug

Known issues

breakingThe `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').

affects: >=1.0.0

gotchaCoordinates 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)`.

affects: All

gotchaA `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)`.

affects: All

deprecatedSupport 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.

affects: >=2.5.0

Errors

Common errors & fixes

ValueError: Latitude {lat} is out of range [-90, 90]

The input latitude or longitude value provided to the `haversine` function is outside its valid geographical range (latitude: -90 to 90, longitude: -180 to 180).

fix

Ensure that the latitude and longitude values passed as `point1` and `point2` are within their valid ranges. The library can also automatically normalize points with `normalize=True`.

TypeError: haversine() missing 1 required positional argument: 'point2'

The `haversine` function expects two positional arguments, `point1` and `point2`, which should each be a tuple of (latitude, longitude). This error occurs when individual latitude and longitude components are passed as separate arguments, or an incorrect number of arguments is provided.

fix

Pass the coordinates as two tuples, each containing (latitude, longitude). For example: `haversine((lat1, lon1), (lat2, lon2))`.

ImportError: cannot import name 'haversine' from 'haversine' (unknown location)

This error typically occurs when there is a local Python file named `haversine.py` in the same directory or on the Python path, which shadows the actual installed `haversine` library.

fix

Rename your local `haversine.py` file to something else (e.g., `my_haversine_script.py`) to avoid conflicts with the installed package.

AttributeError: module 'haversine' has no attribute 'Unit'

The `Unit` enumeration was not explicitly imported from the `haversine` library, even though the `haversine` function itself might have been imported.

fix

Explicitly import `Unit` alongside `haversine` from the library: `from haversine import haversine, Unit`.

Upgrade

Version history

2.9.0latest on PyPI · released Nov 28, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/mapado/haversine ↗

packagehttps://pypi.org/project/haversine/ ↗