# Reverse Geocode
Reverse Geocode takes a latitude / longitude coordinate and returns the nearest known country, state, and city.
This can be useful when you need to reverse geocode a large number of coordinates so a web API is not practical.
The geocoded locations are from [geonames](http://download.geonames.org/export/dump/). This data is then structured in to a [k-d tree](http://en.wikipedia.org/wiki/K-d_tree>) for efficiently finding the nearest neighbour.
Note that as this is point based and not a polygon based lookup it will only give a rough idea of the location/city.
## Example usage
Example reverse geocoding a coordinate:
```
>>> import reverse_geocode
>>> melbourne_coord = -37.81, 144.96
>>> reverse_geocode.get(melbourne_coord)
{'country_code': 'AU', 'city': 'Melbourne', 'latitude': -37.814, 'longitude': 144.96332, 'population': 4917750, 'state': 'Victoria', 'country': 'Australia'}
```
Example reverse geocoding a list of coordinates:
```
>>> nyc_coord = 40.71427000, -74.00597000
>>> reverse_geocode.search((melbourne_coord, nyc_coord))
[{'country_code': 'AU', 'city': 'Melbourne', 'latitude': -37.814, 'longitude': 144.96332, 'population': 4917750, 'state': 'Victoria', 'country': 'Australia'},
{'country_code': 'US', 'city': 'New York City', 'latitude': 40.71427, 'longitude': -74.00597, 'population': 8804190, 'state': 'New York', 'country': 'United States'}]
```
By default the nearest known location is returned, which may not be as expected when there is a much larger city nearby.
For example querying for the following coordinate near NYC will return Seaport:
```
>>> nyc_coordinate = 40.71, -74.00
>>> reverse_geocode.get(nyc_coordinate)
{'country_code': 'US', 'city': 'Seaport', 'latitude': 40.70906, 'longitude': -74.00317, 'population': 8385, 'state': 'New York', 'county': 'New York County', 'country': 'United States'}
```
To filter for larger cities a minimum population can be set. Using a minimum population of `100000` with the above coordinate now returns NYC:
```
>>> reverse_geocode.get(nyc_coordinate, min_population=100000)
{'country_code': 'US', 'city': 'New York City', 'latitude': 40.71427, 'longitude': -74.00597, 'population': 8804190, 'state': 'New York', 'country': 'United States'}
```
## Install
```
pip install reverse-geocode
```
Raw data
{
"_id": null,
"home_page": "https://github.com/richardpenman/reverse_geocode/",
"name": "reverse-geocode",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Richard Penman",
"author_email": "richard.penman@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8b/7c/552b672bee743ff06f5165e67aa1bbbeea97a11d8242da8ff934ac74743d/reverse_geocode-1.6.5.tar.gz",
"platform": null,
"description": "# Reverse Geocode\n\nReverse Geocode takes a latitude / longitude coordinate and returns the nearest known country, state, and city.\nThis can be useful when you need to reverse geocode a large number of coordinates so a web API is not practical.\n\nThe geocoded locations are from [geonames](http://download.geonames.org/export/dump/). This data is then structured in to a [k-d tree](http://en.wikipedia.org/wiki/K-d_tree>) for efficiently finding the nearest neighbour. \n\nNote that as this is point based and not a polygon based lookup it will only give a rough idea of the location/city.\n\n\n## Example usage\n\nExample reverse geocoding a coordinate:\n\n```\n>>> import reverse_geocode\n>>> melbourne_coord = -37.81, 144.96\n>>> reverse_geocode.get(melbourne_coord)\n{'country_code': 'AU', 'city': 'Melbourne', 'latitude': -37.814, 'longitude': 144.96332, 'population': 4917750, 'state': 'Victoria', 'country': 'Australia'}\n```\n\nExample reverse geocoding a list of coordinates:\n```\n>>> nyc_coord = 40.71427000, -74.00597000\n>>> reverse_geocode.search((melbourne_coord, nyc_coord))\n[{'country_code': 'AU', 'city': 'Melbourne', 'latitude': -37.814, 'longitude': 144.96332, 'population': 4917750, 'state': 'Victoria', 'country': 'Australia'},\n {'country_code': 'US', 'city': 'New York City', 'latitude': 40.71427, 'longitude': -74.00597, 'population': 8804190, 'state': 'New York', 'country': 'United States'}]\n```\n\nBy default the nearest known location is returned, which may not be as expected when there is a much larger city nearby.\nFor example querying for the following coordinate near NYC will return Seaport:\n\n```\n>>> nyc_coordinate = 40.71, -74.00\n>>> reverse_geocode.get(nyc_coordinate)\n{'country_code': 'US', 'city': 'Seaport', 'latitude': 40.70906, 'longitude': -74.00317, 'population': 8385, 'state': 'New York', 'county': 'New York County', 'country': 'United States'}\n```\n\nTo filter for larger cities a minimum population can be set. Using a minimum population of `100000` with the above coordinate now returns NYC:\n \n```\n>>> reverse_geocode.get(nyc_coordinate, min_population=100000)\n{'country_code': 'US', 'city': 'New York City', 'latitude': 40.71427, 'longitude': -74.00597, 'population': 8804190, 'state': 'New York', 'country': 'United States'}\n```\n\n\n## Install\n\n```\npip install reverse-geocode\n```\n",
"bugtrack_url": null,
"license": "lgpl",
"summary": "Reverse geocode the given latitude / longitude",
"version": "1.6.5",
"project_urls": {
"Homepage": "https://github.com/richardpenman/reverse_geocode/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c9bd61f9997710048902cef3c08572cfb502031dfaf8915157372ac15210a1aa",
"md5": "af4ea64bc45f80a65fb2d634ebf1068e",
"sha256": "3937d390da78dd1eb17129d93c827398331e604258cd95624ad43471ba8f30f5"
},
"downloads": -1,
"filename": "reverse_geocode-1.6.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af4ea64bc45f80a65fb2d634ebf1068e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 3308565,
"upload_time": "2024-06-12T16:45:11",
"upload_time_iso_8601": "2024-06-12T16:45:11.308930Z",
"url": "https://files.pythonhosted.org/packages/c9/bd/61f9997710048902cef3c08572cfb502031dfaf8915157372ac15210a1aa/reverse_geocode-1.6.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b7c552b672bee743ff06f5165e67aa1bbbeea97a11d8242da8ff934ac74743d",
"md5": "8e89304c03fe17a523c4d95eafb2eeba",
"sha256": "032aa42e76c76bc6729557eb247a6cc4b7817cb4e5eaef48437115f20ad7ae41"
},
"downloads": -1,
"filename": "reverse_geocode-1.6.5.tar.gz",
"has_sig": false,
"md5_digest": "8e89304c03fe17a523c4d95eafb2eeba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3311233,
"upload_time": "2024-06-12T16:45:15",
"upload_time_iso_8601": "2024-06-12T16:45:15.574314Z",
"url": "https://files.pythonhosted.org/packages/8b/7c/552b672bee743ff06f5165e67aa1bbbeea97a11d8242da8ff934ac74743d/reverse_geocode-1.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-12 16:45:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "richardpenman",
"github_project": "reverse_geocode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"1.26.4"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.12.0"
]
]
}
],
"lcname": "reverse-geocode"
}
JSON
