{"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":"en","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,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}