{"id":13501968,"url":"https://github.com/thampiman/reverse-geocoder","last_synced_at":"2025-05-14T11:11:48.240Z","repository":{"id":29386880,"uuid":"32921926","full_name":"thampiman/reverse-geocoder","owner":"thampiman","description":"A fast, offline reverse geocoder in Python","archived":false,"fork":false,"pushed_at":"2023-03-19T10:52:18.000Z","size":25980,"stargazers_count":1884,"open_issues_count":44,"forks_count":160,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-05-12T13:53:50.541Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thampiman.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2015-03-26T10:51:32.000Z","updated_at":"2025-05-07T06:19:55.000Z","dependencies_parsed_at":"2023-01-14T15:00:35.236Z","dependency_job_id":"b2fbb137-17b3-4342-bc3a-d049b09b34d4","html_url":"https://github.com/thampiman/reverse-geocoder","commit_stats":{"total_commits":57,"total_committers":7,"mean_commits":8.142857142857142,"dds":0.1228070175438597,"last_synced_commit":"a81b4095bf2cb7ef84d2187fcbc8945d5d8922d0"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thampiman%2Freverse-geocoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thampiman%2Freverse-geocoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thampiman%2Freverse-geocoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thampiman%2Freverse-geocoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thampiman","download_url":"https://codeload.github.com/thampiman/reverse-geocoder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129523,"owners_count":22019628,"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":[],"created_at":"2024-07-31T22:01:56.887Z","updated_at":"2025-05-14T11:11:43.218Z","avatar_url":"https://github.com/thampiman.png","language":"Python","readme":"Reverse Geocoder\n=================\nA Python library for offline reverse geocoding. It improves on an existing library called [reverse_geocode](https://pypi.python.org/pypi/reverse_geocode/1.0) developed by [Richard Penman](https://bitbucket.org/richardpenman/reverse_geocode).\n\n*UPDATE (15-Sep-16)*: v1.5.1 released! See release notes below.\n\n### About\nAjay Thampi | [@thampiman](https://twitter.com/thampiman) | [opensignal.com](http://opensignal.com) | [ajaythampi.com](http://ajaythampi.com)\n\n## Features\n1. Besides city/town and country code, this library also returns the nearest latitude and longitude and also administrative regions 1 and 2.\n2. This library also uses a parallelised implementation of K-D trees which promises an improved performance especially for large inputs.\n\nBy default, the K-D tree is populated with cities that have a population \u003e 1000. The source of the data is [GeoNames](http://download.geonames.org/export/dump/). You can also load a custom data source so long as it is a comma-separated file with header (like [rg_cities1000.csv](https://github.com/thampiman/reverse-geocoder/blob/master/reverse_geocoder/rg_cities1000.csv)), containing the following columns:\n\n- `lat`: Latitude\n- `lon`: Longitude\n- `name`: Name of place\n- `admin1`: Admin 1 region\n- `admin2`: Admin 2 region\n- `cc`: ISO 3166-1 alpha-2 country code\n\nFor usage instructions, see below.\n\n## Installation\nFor first time installation,\n```\n$ pip install reverse_geocoder\n```\n\nOr upgrade an existing installation using,\n```\n$ pip install --upgrade reverse_geocoder\n```\n\nPackage can be found on [PyPI](https://pypi.python.org/pypi/reverse_geocoder/).\n\n### Dependencies\n1. scipy\n2. numpy\n\n### Release Notes\n1. v1.0 (27-Mar-15) - First version with support for only Python2\n2. v1.1 (28-Mar-15) - Fix for issue [#1](https://github.com/thampiman/reverse-geocoder/issues/1) by [Brandon](https://github.com/bdon)\n3. v1.2 (30-Mar-15) - Support for Python 3, conversion of [Geodetic](http://en.wikipedia.org/wiki/Geodetic_datum) coordinates to [ECEF](http://en.wikipedia.org/wiki/ECEF) for use in K-D trees to find nearest neighbour using the Euclidean distance function. This release fixes issues [#2](https://github.com/thampiman/reverse-geocoder/issues/2) and [#8](https://github.com/thampiman/reverse-geocoder/issues/8). Special thanks to [David](https://github.com/DavidJFelix) for his help in partly fixing [#2](https://github.com/thampiman/reverse-geocoder/issues/2).\n4. v1.3 (11-Apr-15) - This release fixes issues [#9](https://github.com/thampiman/reverse-geocoder/issues/9), [#10](https://github.com/thampiman/reverse-geocoder/issues/10), [#11](https://github.com/thampiman/reverse-geocoder/issues/11) and [#12](https://github.com/thampiman/reverse-geocoder/issues/12). License has been changed from MIT to LGPL (see [#12](https://github.com/thampiman/reverse-geocoder/issues/12)).\n5. v1.4 (08-Jul-16) - Included numpy and scipy as dependencies in setup.  \n6. v1.5 (15-Sep-16) - Support for custom data source and fixes for issues [#16](https://github.com/thampiman/reverse-geocoder/issues/16) and [#24](https://github.com/thampiman/reverse-geocoder/issues/24). Hat tip to [Jason](https://github.com/swails) and [Gregoire](https://github.com/geekingfrog).\n7. v1.5.1 (15-Sep-16) - Fix for [#26](https://github.com/thampiman/reverse-geocoder/issues/26).\n\n## Usage\nThe library supports two modes:\n\n1. Mode 1: Single-threaded K-D Tree (similar to [reverse_geocode](https://pypi.python.org/pypi/reverse_geocode/1.0))\n2. Mode 2: Multi-threaded K-D Tree (default)\n\n```python\nimport reverse_geocoder as rg\n\ncoordinates = (51.5214588,-0.1729636),(9.936033, 76.259952),(37.38605,-122.08385)\n\nresults = rg.search(coordinates) # default mode = 2\n\nprint results\n```\n\nThe above code will output the following:\n```\n\t[{'name': 'Bayswater', \n      'cc': 'GB', \n      'lat': '51.51116',\n      'lon': '-0.18426', \n      'admin1': 'England', \n      'admin2': 'Greater London'}, \n     {'name': 'Cochin', \n      'cc': 'IN', \n      'lat': '9.93988',\n      'lon': '76.26022', \n      'admin1': 'Kerala', \n      'admin2': 'Ernakulam'},\n     {'name': 'Mountain View', \n      'cc': 'US', \n      'lat': '37.38605',\n      'lon': '-122.08385', \n      'admin1': 'California', \n      'admin2': 'Santa Clara County'}]\n```\n\nIf you'd like to use the single-threaded K-D tree, set mode = 1 as follows:\n```python\nresults = rg.search(coordinates,mode=1)\n```\n\nTo use a custom data source for geocoding, you can load the file in-memory and pass it to the library as follows:\n```python\nimport io\nimport reverse_geocoder as rg\n\ngeo = rg.RGeocoder(mode=2, verbose=True, stream=io.StringIO(open('custom_source.csv', encoding='utf-8').read()))\ncoordinates = (51.5214588,-0.1729636),(9.936033, 76.259952),(37.38605,-122.08385)\nresults = geo.query(coordinates)\n```\n\nAs mentioned above, the custom data source must be comma-separated with a header as [rg_cities1000.csv](https://github.com/thampiman/reverse-geocoder/blob/master/reverse_geocoder/rg_cities1000.csv).\n\n## Performance\nThe performance of modes 1 and 2 are plotted below for various input sizes.\n\n![Performance Comparison](performance.png)\n\nMode 2 runs ~2x faster for very large inputs (10M coordinates).\n\n## Acknowledgements\n1. Major inspiration is from Richard Penman's [reverse_geocode](https://bitbucket.org/richardpenman/reverse_geocode) library \n2. Parallelised implementation of K-D Trees is extended from this [article](http://folk.uio.no/sturlamo/python/multiprocessing-tutorial.pdf) by [Sturla Molden](https://github.com/sturlamolden)\n3. Geocoded data is from [GeoNames](http://download.geonames.org/export/dump/)\n\n## License\nCopyright (c) 2015 Ajay Thampi and contributors. This code is licensed under the LGPL License.","funding_links":[],"categories":["Python","库 Libraries","Feature Extraction"],"sub_categories":["地理空间 Geospatial","Geolocation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthampiman%2Freverse-geocoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthampiman%2Freverse-geocoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthampiman%2Freverse-geocoder/lists"}