Install & Compatibility
Where this runs
tested against v1.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.301s · 239.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 10.1s · import 1.235s · 231MB
238MB installed
● package 238MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
rg.search
✓ import reverse_geocoder as rg
✗ import reverse_geocode
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()`.
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
Debug
Known issues
deprecatedThe 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.fixFor 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.
affects: All versions post v1.5.1
gotchaThis 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.fixUnderstand 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.
affects: All versions
gotchaPrior 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.fixEnsure 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.
affects: <1.2
gotchaVersion 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.fixReview 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.
affects: <1.5
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'reverse_geocoder'
The 'reverse-geocoder' library has not been installed or is not accessible in the current Python environment.
fixpip install reverse-geocoder
AttributeError: module 'reverse_geocoder' has no attribute 'query'
The 'query' method must be called on an instance of the 'RGeo' class, not directly on the 'reverse_geocoder' module.
fiximport reverse_geocoder as rg
rgeo = rg.RGeo()
rgeo.query([(40.7128, -74.0060)])
TypeError: 'float' object is not iterable
The 'query' method expects a list of (latitude, longitude) tuples, but a single float or tuple was provided directly.
fiximport reverse_geocoder as rg
rgeo = rg.RGeo()
rgeo.query([(40.7128, -74.0060)]) # Wrap the single coordinate pair in a list of tuples
ImportError: cannot import name 'get_data_filepath' from 'reverse_geocoder'
The 'get_data_filepath' function was moved to a submodule ('reverse_geocoder.utils') and is no longer directly importable from the top-level 'reverse_geocoder' module.
fixfrom reverse_geocoder.utils import get_data_filepath
Upgrade
Version history
1.5.1latest on PyPI · released Sep 15, 2016
Audit
Dependencies
numpyrequiredUsed for numerical operations and array handling within the K-D tree implementation.
scipyrequiredProvides scientific computing tools, likely for spatial data structures and algorithms (e.g., cKDTree).