Reverse Geocoder

1.5.1 · maintenance · verified Wed Apr 15

Reverse Geocoder is a fast, offline Python library designed to convert geographic coordinates (latitude, longitude) into human-readable location data such as city, country, and administrative regions. It improves upon an existing library by utilizing a parallelized K-D tree for enhanced performance, especially for large inputs. The library uses GeoNames data, with a default population filter of >1000, and allows for custom data sources. The current version is 1.5.1, with its last release in September 2016, indicating a maintenance phase rather than active development.

Warnings

deprecated The library's last release (v1.5.1) was in September 2016. It is no longer actively maintained, which may lead to compatibility issues with newer Python versions or other dependencies, and the underlying geodata may be outdated.
Fix: For new projects, consider more actively maintained alternatives or be prepared to fork and maintain the library yourself. If using, thoroughly test with your specific Python environment and data.
gotcha This library performs point-based reverse geocoding, finding the 'nearest' city or town from its GeoNames data. It does not provide precise street-level addresses or polygon-based lookups, offering only a 'rough idea' of the location.
Fix: Understand the limitations: this library is suitable for finding general location names (city, country, admin regions) but not for high-precision address lookups. For precise address data, consider online reverse geocoding APIs.
gotcha Prior to v1.2 (released March 2015), the library only supported Python 2. While current versions support Python 3, older installations might be Python 2 specific.
Fix: Ensure you are using `reverse-geocoder` v1.2 or newer if working with Python 3. `pip install --upgrade reverse-geocoder` should update to the latest compatible version.
gotcha Version 1.5 introduced support for custom data sources. If upgrading from pre-1.5 versions and expecting specific data behavior, changes in default data loading or API calls for custom sources might be required.
Fix: Review the GitHub documentation on custom data sources if you are upgrading from an older version and rely on specific data files or wish to use this new feature.

Install

pip install reverse-geocoder Install stable version

Imports

rg.search
wrong:
```
import reverse_geocode
```
correct:
```
import reverse_geocoder as rg
```
The PyPI package `reverse-geocoder` imports as `reverse_geocoder` (with an underscore). A similarly named but different package, `reverse-geocode` (with a hyphen), has a different API, notably using `reverse_geocode.get()`.

Quickstart

This quickstart demonstrates how to import the library and perform reverse geocoding for a list of coordinate pairs. The `search` function returns a list of dictionaries, each containing details like city name, administrative regions, country code, and the nearest latitude/longitude from its internal database.

import reverse_geocoder as rg

# List of (latitude, longitude) tuples
coordinates = [
    (51.521458, -0.138850), # London
    (35.689487, 139.691706), # Tokyo
    (40.7127837, -74.0059413) # New York City
]

# Perform reverse geocoding
results = rg.search(coordinates)

# Print the results
for coord, result in zip(coordinates, results):
    print(f"Coordinates: {coord} -> Found: {result['name']}, {result['admin1']}, {result['cc']}")

# Expected output format (values may vary slightly based on data source)
# Coordinates: (51.521458, -0.13885) -> Found: London, England, GB
# Coordinates: (35.689487, 139.691706) -> Found: Tokyo, Tōkyō, JP
# Coordinates: (40.7127837, -74.0059413) -> Found: New York City, New York, US

view raw JSON →