{"id":7674,"library":"reverse-geocode","title":"Reverse Geocode","description":"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.","status":"active","version":"1.6.6","language":"en","source_language":"en","source_url":"https://github.com/richardpenman/reverse_geocode/","tags":["geocoding","reverse geocoding","offline","location","geonames"],"install":[{"cmd":"pip install reverse-geocode","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for K-D tree implementation to efficiently find nearest neighbors.","package":"scipy"},{"reason":"Fundamental package for numerical computing in Python, often used with SciPy for array operations.","package":"numpy"}],"imports":[{"note":"The primary functions `search` and `get` are typically accessed directly as methods of the imported module object.","wrong":"from reverse_geocode import search","symbol":"reverse_geocode","correct":"import reverse_geocode"}],"quickstart":{"code":"import reverse_geocode\n\n# Example for a single coordinate\nmelbourne_coord = (-37.81, 144.96)\nresult_single = reverse_geocode.get(melbourne_coord)\nprint(f\"Single result: {result_single}\")\n\n# Example for multiple coordinates\ncoordinates = (\n    (40.71427000, -74.00597000), # New York City\n    (-37.81, 144.96) # Melbourne\n)\nresults_batch = reverse_geocode.search(coordinates)\nprint(f\"Batch results: {results_batch}\")","lang":"python","description":"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."},"warnings":[{"fix":"For precise address-level reverse geocoding, consider using external API-based solutions like Geoapify, Geocodio, or Google Maps Platform.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":"All versions when using SciPy >= 1.11"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install reverse-geocode`","cause":"The `reverse-geocode` library has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'reverse_geocode'"},{"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))`.","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.","error":"TypeError: 'float' object is not iterable"},{"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.","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.","error":"Output includes: 'Loading formatted geocoded file...'"}]}