{"id":13937174,"url":"https://github.com/mapado/haversine","last_synced_at":"2025-05-14T00:09:56.521Z","repository":{"id":6535507,"uuid":"7776734","full_name":"mapado/haversine","owner":"mapado","description":"Calculate the distance between 2 points on Earth","archived":false,"fork":false,"pushed_at":"2025-04-24T06:41:36.000Z","size":176,"stargazers_count":343,"open_issues_count":7,"forks_count":64,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-24T07:43:41.638Z","etag":null,"topics":["distance","earth","haversine","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mapado.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-01-23T14:56:11.000Z","updated_at":"2025-04-24T06:41:41.000Z","dependencies_parsed_at":"2024-01-18T10:33:10.103Z","dependency_job_id":"9b542847-08ed-4177-b3ce-6d32ef1a0de5","html_url":"https://github.com/mapado/haversine","commit_stats":{"total_commits":185,"total_committers":27,"mean_commits":6.851851851851852,"dds":0.427027027027027,"last_synced_commit":"4834f8c25d616264f80e4a902f1b8b6ab5eee587"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapado%2Fhaversine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapado%2Fhaversine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapado%2Fhaversine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapado%2Fhaversine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mapado","download_url":"https://codeload.github.com/mapado/haversine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254044231,"owners_count":22005107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distance","earth","haversine","python"],"created_at":"2024-08-07T23:03:21.490Z","updated_at":"2025-05-14T00:09:51.511Z","avatar_url":"https://github.com/mapado.png","language":"Python","readme":"# Haversine\n\nCalculate the distance (in various units) between two points on Earth using their latitude and longitude.\n\n## Installation\n\n```sh\npip install haversine\n```\n\n## Usage\n\n### Calculate the distance between Lyon and Paris\n\n```python\nfrom haversine import haversine, Unit\n\nlyon = (45.7597, 4.8422) # (lat, lon)\nparis = (48.8567, 2.3508)\n\nhaversine(lyon, paris)\n\u003e\u003e 392.2172595594006  # in kilometers\n\nhaversine(lyon, paris, unit=Unit.MILES)\n\u003e\u003e 243.71250609539814  # in miles\n\n# you can also use the string abbreviation for units:\nhaversine(lyon, paris, unit='mi')\n\u003e\u003e 243.71250609539814  # in miles\n\nhaversine(lyon, paris, unit=Unit.NAUTICAL_MILES)\n\u003e\u003e 211.78037755311516  # in nautical miles\n```\n\nThe lat/lon values need to be provided in degrees of the ranges [-90,90] (lat) and [-180,180] (lon).\nIf values are outside their ranges, an error will be raised. This can be avoided by automatic normalization via the `normalize` parameter.\n\nThe `haversine.Unit` enum contains all supported units:\n\n```python\nimport haversine\n\nprint(tuple(haversine.Unit))\n```\n\noutputs\n\n```text\n(\u003cUnit.KILOMETERS: 'km'\u003e, \u003cUnit.METERS: 'm'\u003e, \u003cUnit.MILES: 'mi'\u003e,\n \u003cUnit.NAUTICAL_MILES: 'nmi'\u003e, \u003cUnit.FEET: 'ft'\u003e, \u003cUnit.INCHES: 'in'\u003e,\n \u003cUnit.RADIANS: 'rad'\u003e, \u003cUnit.DEGREES: 'deg'\u003e)\n```\n\n#### Note for radians and degrees\n\nThe radian and degrees returns the [great circle distance](https://en.wikipedia.org/wiki/Great-circle_distance) between two points on a sphere.\n\nNotes:\n\n- on a unit-sphere the angular distance in radians equals the distance between the two points on the sphere (definition of radians)\n- When using \"degree\", this angle is just converted from radians to degrees\n\n### Inverse Haversine Formula\n\nCalculates a point from a given vector (distance and direction) and start point.\nCurrently explicitly supports both cardinal (north, east, south, west) and intercardinal (northeast, southeast, southwest, northwest) directions.\nBut also allows for explicit angles expressed in Radians.\n\n## Example: Finding arbitary point from Paris\n\n```python\nfrom haversine import inverse_haversine, Direction\nfrom math import pi\nparis = (48.8567, 2.3508) # (lat, lon)\n# Finding 32 km west of Paris\ninverse_haversine(paris, 32, Direction.WEST)\n# returns tuple (48.85587279023947, 1.9134085092836945)\n# Finding 32 km southwest of Paris\ninverse_haversine(paris, 32, pi * 1.25)\n# returns tuple (48.65279552300661, 2.0427666779658806)\n# Finding 50 miles north of Paris\ninverse_haversine(paris, 50, Direction.NORTH, unit=Unit.MILES)\n# returns tuple (49.58035791599536, 2.3508)\n# Finding 10 nautical miles south of Paris\ninverse_haversine(paris, 10, Direction.SOUTH, unit=Unit.NAUTICAL_MILES)\n# returns tuple (48.690145868497645, 2.3508)\n```\n\n### Performance optimisation for distances between all points in two vectors\n\nYou will need to install [numpy](https://pypi.org/project/numpy/) in order to gain performance with vectors.\nFor optimal performance, you can turn off coordinate checking by adding `check=False` and install the optional packages [numba](https://pypi.org/project/numba/) and [icc_rt](https://pypi.org/project/icc_rt/).\n\nYou can then do this:\n\n```python\nfrom haversine import haversine_vector, Unit\n\nlyon = (45.7597, 4.8422) # (lat, lon)\nparis = (48.8567, 2.3508)\nnew_york = (40.7033962, -74.2351462)\n\nhaversine_vector([lyon, lyon], [paris, new_york], Unit.KILOMETERS)\n\n\u003e\u003e array([ 392.21725956, 6163.43638211])\n```\n\nIt is generally slower to use `haversine_vector` to get distance between two points, but can be really fast to compare distances between two vectors.\n\n### Combine matrix\n\nYou can generate a matrix of all combinations between coordinates in different vectors by setting `comb` parameter as True.\n\n```python\nfrom haversine import haversine_vector, Unit\n\nlyon = (45.7597, 4.8422) # (lat, lon)\nlondon = (51.509865, -0.118092)\nparis = (48.8567, 2.3508)\nnew_york = (40.7033962, -74.2351462)\n\nhaversine_vector([lyon, london], [paris, new_york], Unit.KILOMETERS, comb=True)\n\n\u003e\u003e array([[ 392.21725956,  343.37455271],\n \t  [6163.43638211, 5586.48447423]])\n```\n\nThe output array from the example above returns the following table:\n\n|        |       Paris       |       New York       |\n| ------ | :---------------: | :------------------: |\n| Lyon   |  Lyon \u003c\\-\u003e Paris  |  Lyon \u003c\\-\u003e New York  |\n| London | London \u003c\\-\u003e Paris | London \u003c\\-\u003e New York |\n\nBy 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_.\n\n## Contributing\n\nClone the project.\n\nInstall [pipenv](https://github.com/pypa/pipenv).\n\nRun `pipenv install --dev`\n\nLaunch test with `pipenv run pytest`\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapado%2Fhaversine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmapado%2Fhaversine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapado%2Fhaversine/lists"}