Calculate the distance between 2 points on Earth.
Project description
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.71250609539814 # in miles
# you can also use the string abbreviation for units:
haversine(lyon, paris, unit='mi')
>> 243.71250609539814 # 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 unitsphere 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 (48.85587279023947, 1.9134085092836945)
# Finding 32 km southwest of Paris
inverse_haversine(paris, 32, pi * 1.25)
# returns tuple (48.65279552300661, 2.0427666779658806)
# Finding 50 miles north of Paris
inverse_haversine(paris, 50, Direction.NORTH, unit=Unit.MILES)
# returns tuple (49.58035791599536, 2.3508)
# Finding 10 nautical miles south of Paris
inverse_haversine(paris, 10, Direction.SOUTH, unit=Unit.NAUTICAL_MILES)
# returns tuple (48.690145868497645, 2.3508)
Performance optimisation for distances between all points in two vectors
You will need to install numpy in order to gain performance with vectors.
For optimal performance, you can turn off coordinate checking by adding check=False
and install the optional packages numba and icc_rt.
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
Project details
Release history Release notifications  RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for haversine2.8.1py2.py3noneany.whl
Algorithm  Hash digest  

SHA256  1acdd7e35115e00346898984acd55b0827d289df434efef98376f0bed37c8fa7 

MD5  54dd7ffbf5f39ba7eff08191c4d22113 

BLAKE2b256  5bf1b7274966f0b5b665d9114e86d09c6bc87d241781d63d8817323dcfa940c6 