Reverse Geocode

1.6.6 · active · verified Thu Apr 16

Reverse Geocode is a Python library (current version 1.6.6) for offline reverse geocoding. It translates latitude/longitude coordinates into the nearest known country, state, and city using a k-d tree structure built from GeoNames data. This is particularly useful for batch processing a large number of coordinates without relying on external web APIs. The project maintains an infrequent release cadence.

Common errors

```
ModuleNotFoundError: No module named 'reverse_geocode'
```
cause The `reverse-geocode` library has not been installed in your current Python environment.

fix Install the library using pip: `pip install reverse-geocode`
```
TypeError: 'float' object is not iterable
```
cause The `reverse_geocode.search()` method expects an iterable of (latitude, longitude) tuples, even if you are querying only one coordinate. Passing single float values directly will result in this error. The `get()` method expects a single (latitude, longitude) tuple.

fix For `search()`, pass a list or tuple of coordinate tuples, e.g., `reverse_geocode.search([(lat, lon)])` for one, or `reverse_geocode.search([(lat1, lon1), (lat2, lon2)])` for multiple. For `get()`, pass a single coordinate tuple, e.g., `reverse_geocode.get((lat, lon))`.
```
Output includes: 'Loading formatted geocoded file...'
```
cause This is not an error but a normal verbose message indicating that the library is loading its internal GeoNames data into memory. This typically happens only on the first call to a geocoding function within a Python session.

fix No fix is required as this is expected behavior. The message will not appear on subsequent calls unless the `RGeocoder` instance is re-initialized.

Warnings

gotcha Accuracy Limitation: This library performs point-based lookups using a k-d tree and GeoNames data, not polygon-based lookups. As such, it provides an *approximate* location (nearest known city, state, country) rather than a precise address, which may not be suitable for applications requiring high geocoding precision.
Fix: For precise address-level reverse geocoding, consider using external API-based solutions like Geoapify, Geocodio, or Google Maps Platform.
gotcha Data Source Limitations: By default, the K-D tree is populated with cities from GeoNames having a population greater than 1000. This means smaller towns or very specific points might not be accurately resolved. For custom or more granular data sources, a specific CSV format (`lat`, `lon`, `name`, `admin1`, `admin2`, `cc`) must be provided.
Fix: If default data is insufficient, prepare a custom CSV file with the required header and columns, then initialize the geocoder with it using `rg.RGeocoder(stream=io.StringIO(open('custom_source.csv', encoding='utf-8').read()))` (requires importing `io`).
gotcha Potential SciPy Dependency Conflict: A related project, `reverse_geocoder_whl` (an improvement upon this library), noted a breaking change in SciPy 1.11, requiring `scipy < 1.11` for compatibility. While not explicitly stated for `reverse-geocode` itself, users might encounter compatibility issues or errors with newer SciPy versions due to shared underlying algorithms and data structures.
Fix: If errors related to SciPy arise, try downgrading your SciPy installation to a version below 1.11, e.g., `pip install 'scipy<1.11'`.

Install

pip install reverse-geocode Install latest version

Imports

reverse_geocode
wrong:
```
from reverse_geocode import search
```
correct:
```
import reverse_geocode
```
The primary functions `search` and `get` are typically accessed directly as methods of the imported module object.

Quickstart

This quickstart demonstrates how to perform reverse geocoding for both single and multiple latitude/longitude coordinates using the `get()` and `search()` functions, respectively. The results include country code, city, latitude, longitude, population, state, and country.

import reverse_geocode

# Example for a single coordinate
melbourne_coord = (-37.81, 144.96)
result_single = reverse_geocode.get(melbourne_coord)
print(f"Single result: {result_single}")

# Example for multiple coordinates
coordinates = (
    (40.71427000, -74.00597000), # New York City
    (-37.81, 144.96) # Melbourne
)
results_batch = reverse_geocode.search(coordinates)
print(f"Batch results: {results_batch}")

view raw JSON →