{"id":2528,"library":"haversine","title":"Haversine","description":"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.","status":"active","version":"2.9.0","language":"python","source_language":"en","source_url":"https://github.com/mapado/haversine","tags":["geospatial","distance","haversine","gps","coordinates","mapping"],"install":[{"cmd":"pip install haversine","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Import `Unit` enum for specifying output distance units clearly. While string abbreviations work, `Unit` provides type safety and clarity.","wrong":"from haversine import haversine","symbol":"haversine","correct":"from haversine import haversine, Unit"}],"quickstart":{"code":"from haversine import haversine, Unit\n\n# Define points as (latitude, longitude) tuples\nlyon = (45.7597, 4.8422)\nparis = (48.8567, 2.3508)\n\n# Calculate distance in kilometers (default)\ndistance_km = haversine(lyon, paris)\nprint(f\"Distance between Lyon and Paris: {distance_km:.2f} km\")\n\n# Calculate distance in miles\ndistance_miles = haversine(lyon, paris, unit=Unit.MILES)\nprint(f\"Distance between Lyon and Paris: {distance_miles:.2f} miles\")\n\n# Calculate distance in meters using string abbreviation\ndistance_m = haversine(lyon, paris, unit='m')\nprint(f\"Distance between Lyon and Paris: {distance_m:.2f} meters\")","lang":"python","description":"Calculate the distance between two geographical points (Lyon and Paris) in kilometers, miles, and meters. Points are provided as (latitude, longitude) tuples."},"warnings":[{"fix":"Replace `miles=True` or `nautical_miles=True` with `unit=Unit.MILES` or `unit=Unit.NAUTICAL_MILES` (or their string equivalents 'mi' / 'nmi').","message":"The `miles` and `nautical_miles` boolean parameters were removed in version 1.0.0 (October 2018) and replaced by the unified `unit` parameter.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always ensure your point tuples are structured as `(latitude, longitude)`, for example `point1 = (lat1, lon1)`.","message":"Coordinates must be provided as `(latitude, longitude)` tuples. A common mistake is to reverse the order to `(longitude, latitude)`, leading to incorrect distance calculations.","severity":"gotcha","affected_versions":"All"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade to Python 3.5 or newer. The `python_requires` is `>=3.5` for current versions.","message":"Support for Python 2.7 was officially dropped in version 2.5.0.","severity":"deprecated","affected_versions":">=2.5.0"}],"env_vars":null,"search_vec":"'2.9.0':7 'activ':51 'analysi':45 'calcul':8 'circl':12 'common':41 'coordin':61 'current':5 'develop':52 'distanc':13,58 'earth':18 'formula':27 'geospati':44,57 'given':19 'gps':60 'great':11 'great-circl':10 'haversin':1,3,26,59 'kilomet':33 'latitud':21 'librari':4 'like':32 'longitud':23 'maintain':49 'map':62 'meter':34 'mile':35,38 'nautic':37 'navig':47 'point':16 'regular':55 'status':53 'support':29 'two':15 'unit':31 'updat':56 'use':24,42 'various':30 'version':6","created_at":"2026-04-11T01:31:55.225099+00:00","updated_at":"2026-04-16T15:33:01.234127+00:00","problems":[{"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`.","cause":"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).","error":"ValueError: Latitude {lat} is out of range [-90, 90]"},{"fix":"Pass the coordinates as two tuples, each containing (latitude, longitude). For example: `haversine((lat1, lon1), (lat2, lon2))`.","cause":"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.","error":"TypeError: haversine() missing 1 required positional argument: 'point2'"},{"fix":"Rename your local `haversine.py` file to something else (e.g., `my_haversine_script.py`) to avoid conflicts with the installed package.","cause":"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.","error":"ImportError: cannot import name 'haversine' from 'haversine' (unknown location)"},{"fix":"Explicitly import `Unit` alongside `haversine` from the library: `from haversine import haversine, Unit`.","cause":"The `Unit` enumeration was not explicitly imported from the `haversine` library, even though the `haversine` function itself might have been imported.","error":"AttributeError: module 'haversine' has no attribute 'Unit'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.9.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mapado/haversine","docs":null,"changelog":null,"pypi":"https://pypi.org/project/haversine/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}