Skip to main content

Haversine

Calculate the distance (in various units) between two points on Earth using their latitude and longitude.

Installation

pip install haversine

Usage

Calculate the distance between Lyon and Paris

from haversine import haversine, Unit

lyon = (45.7597, 4.8422) # (lat, lon)
paris = (48.8567, 2.3508)

haversine(lyon, paris)
>> 392.2172595594006  # in kilometers

haversine(lyon, paris, unit=Unit.MILES)
>> 243.71201856934454  # in miles

# you can also use the string abbreviation for units:
haversine(lyon, paris, unit='mi')
>> 243.71201856934454  # in miles

haversine(lyon, paris, unit=Unit.NAUTICAL_MILES)
>> 211.78037755311516  # in nautical miles

The lat/lon values need to be provided in degrees of the ranges [-90,90] (lat) and [-180,180] (lon). If values are outside their ranges, an error will be raised. This can be avoided by automatic normalization via the normalize parameter.

The haversine.Unit enum contains all supported units:

import haversine

print(tuple(haversine.Unit))

outputs

(<Unit.KILOMETERS: 'km'>, <Unit.METERS: 'm'>, <Unit.MILES: 'mi'>,
 <Unit.NAUTICAL_MILES: 'nmi'>, <Unit.FEET: 'ft'>, <Unit.INCHES: 'in'>,
 <Unit.RADIANS: 'rad'>, <Unit.DEGREES: 'deg'>)

Note for radians and degrees

The radian and degrees returns the great circle distance between two points on a sphere.

Notes:

  • on a unit-sphere the angular distance in radians equals the distance between the two points on the sphere (definition of radians)
  • When using "degree", this angle is just converted from radians to degrees

Inverse Haversine Formula

Calculates a point from a given vector (distance and direction) and start point. Currently explicitly supports both cardinal (north, east, south, west) and intercardinal (northeast, southeast, southwest, northwest) directions. But also allows for explicit angles expressed in Radians.

Example: Finding arbitary point from Paris

from haversine import inverse_haversine, Direction
from math import pi
paris = (48.8567, 2.3508) # (lat, lon)
# Finding 32 km west of Paris
inverse_haversine(paris, 32, Direction.WEST)
# returns tuple (49.1444, 2.3508)
# Finding 32 km southwest of Paris
inverse_haversine(paris, 32, pi * 1.25)
# returns tuple (48.5377, 1.8705)
# Finding 50 miles north of Paris
inverse_haversine(paris, 50, Direction.NORTH, unit=Unit.MILES)
# returns tuple (49.5803, 2.3508)
# Finding 10 nautical miles south of Paris
inverse_haversine(paris, 10, Direction.SOUTH, unit=Unit.NAUTICAL_MILES)
# returns tuple (48.6901, 2.3508)

Performance optimisation for distances between all points in two vectors

You will need to add numpy in order to gain performance with vectors.

You can then do this:

from haversine import haversine_vector, Unit

lyon = (45.7597, 4.8422) # (lat, lon)
paris = (48.8567, 2.3508)
new_york = (40.7033962, -74.2351462)

haversine_vector([lyon, lyon], [paris, new_york], Unit.KILOMETERS)

>> array([ 392.21725956, 6163.43638211])

It is generally slower to use haversine_vector to get distance between two points, but can be really fast to compare distances between two vectors.

Combine matrix

You can generate a matrix of all combinations between coordinates in different vectors by setting comb parameter as True.

from haversine import haversine_vector, Unit

lyon = (45.7597, 4.8422) # (lat, lon)
london = (51.509865, -0.118092)
paris = (48.8567, 2.3508)
new_york = (40.7033962, -74.2351462)

haversine_vector([lyon, london], [paris, new_york], Unit.KILOMETERS, comb=True)

>> array([[ 392.21725956,  343.37455271],
 	  [6163.43638211, 5586.48447423]])

The output array from the example above returns the following table:

Paris New York
Lyon Lyon <-> Paris Lyon <-> New York
London London <-> Paris London <-> New York

By definition, if you have a vector a with n elements, and a vector b with m elements. The result matrix M would be $n x m$ and a element M[i,j] from the matrix would be the distance between the ith coordinate from vector a and jth coordinate with vector b.

Contributing

Clone the project.

Install pipenv.

Run pipenv install --dev

Launch test with pipenv run pytest

Metadata

Release files for haversine 2.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for haversine 2.6.0
File Size Uploaded Provenance Actions
haversine-2.6.0.tar.gz 6.1 kB Without provenance Details for haversine-2.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for haversine 2.6.0
File Interpreter ABI Platform Actions
haversine-2.6.0-py2.py3-none-any.whl Python 2, Python 3 none any Details for haversine-2.6.0-py2.py3-none-any.whl

Total release size: 12.9 kB

Release files / haversine-2.6.0.tar.gz

Download URL haversine-2.6.0.tar.gz
Size 6.1 kB
Tags Source
SHA-256 checksum
How to use checksums
eb7c308ba721e86662c1d50427cb9b06f9e7eb9984803d9ec200582425cc4fb7
BLAKE2b-256 checksum
How to use checksums
732f7aed0b56e04786ecfdf5d33e9a23653b923abde917a8fb5d262b8ab9d468
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.7.3

Release files / haversine-2.6.0-py2.py3-none-any.whl

Download URL haversine-2.6.0-py2.py3-none-any.whl
Size 6.8 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
62df22618d148b1b67fc4e282043cc8913d12e2bff356fef87ce1151fd733003
BLAKE2b-256 checksum
How to use checksums
f3be911b910c812bd40e6cde7b55278b2e646c638ee3d73f28da5098a244e0e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.7.3

Security for haversine 2.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page