Registry / data / geocoder

geocoder

JSON →
library1.38.1pypypi✓ verified 25d ago

Geocoder is a simple and consistent geocoding library written in Python. It provides a unified interface for various online geocoding providers like Google, OpenStreetMap Nominatim, Mapbox, and more, abstracting away their different API structures and JSON response schemas. The current version is 1.38.1.

pip install geocoder
INSTALL
IMPORT
SIG · GEOCODER
G
geocoder
datapythonv1.38.1
Install
2.8s avg
Import
504ms
Disk
25MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.38.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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.524s · 26.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.8s · import 0.484s · 27MB
25MB installed
● package 25MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

geocoder
import geocoder

Demonstrates basic forward and reverse geocoding using the `geocoder` library with Google and OpenStreetMap Nominatim providers. It also shows how to retrieve API keys from environment variables for other providers like Mapbox.

import geocoder import os # Geocoding an address using Google # An API key might be required for production use or higher quotas. # Set GOOGLE_API_KEY in your environment variables for security. google_api_key = os.environ.get("GOOGLE_API_KEY", "") g = geocoder.google("Mountain View, CA", key=google_api_key) if g.ok: print(f"Google: Latitude: {g.latlng[0]}, Longitude: {g.latlng[1]}") print(f"Address: {g.address}") else: print(f"Google Geocoding failed: {g.status}") # Reverse geocoding using OpenStreetMap Nominatim (often no API key needed for basic use) # For production or heavy use with Nominatim, providing a unique 'user_agent' is recommended. n = geocoder.osm([37.38605, -122.08385]) # Coordinates for Apple Park if n.ok: print(f"\nNominatim (Reverse): Address: {n.address}") else: print(f"Nominatim Reverse Geocoding failed: {n.status}") # Example with a different provider (e.g., Mapbox), requiring an API key mapbox_api_key = os.environ.get("MAPBOX_API_KEY", "") if mapbox_api_key: m = geocoder.mapbox("San Francisco, CA", key=mapbox_api_key) if m.ok: print(f"\nMapbox: Latitude: {m.latlng[0]}, Longitude: {m.latlng[1]}") print(f"Address: {m.address}") else: print(f"Mapbox Geocoding failed: {m.status}") else: print("\nMAPBOX_API_KEY not set. Skipping Mapbox example.")
Debug
Known issues
breakingAs of version 1.6.0, `geocoder` removed pre-defined API keys, requiring users to pass them explicitly via the `key` parameter or through environment variables. Hardcoding keys is highly discouraged.
fix
Store API keys in environment variables (e.g., `GOOGLE_API_KEY`) and access them using `os.environ.get('YOUR_API_KEY')` when initializing a geocoder or making a request.
affects: >=1.6.0
gotchaExternal geocoding services often impose rate limits and usage quotas. Exceeding these limits can lead to HTTP 429 (Too Many Requests) or other service-specific errors, even with successful API keys.
fix
Implement proper rate limiting and retry logic in your application. For batch geocoding, consider adding `time.sleep()` between requests or utilizing provider-specific batch endpoints if available.
affects: All
gotchaWhile `geocoder` aims to unify responses, the underlying quality, coverage, and specific details returned can vary significantly between different geocoding providers. Relying heavily on specific `raw` response structures might break if providers change their APIs.
fix
Test with multiple providers if broad coverage is needed. Focus on the abstracted `g.latlng`, `g.address`, etc., properties for consistency. If you need provider-specific details, access `g.raw` but be prepared for variations.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'geocoder'
The 'geocoder' library is not installed in the Python environment you are using, or there is an issue with your Python environment's path configuration.
fix
Install the 'geocoder' package using pip: `pip install geocoder` (or `pip3 install geocoder` for Python 3 specific installations). If you have multiple Python versions, ensure you are installing it for the correct interpreter.
AttributeError: module 'geocoder' has no attribute 'google'
You are attempting to access a specific geocoding provider (like 'google', 'osm', or 'ip') using an incorrect syntax or a deprecated method. It can also occur if you have conflicting import statements.
fix
Instead of `geocoder.google('address')`, use the unified `geocoder.geocode('address', provider='google')`. Ensure you only have `import geocoder` and not `from geocoder import google` if you intend to use the main `geocoder` object for provider calls.
Geocode was not successful: REQUEST_DENIED
This error typically indicates a problem with the API key for the chosen geocoding provider (e.g., Google Maps Geocoding API). The key might be missing, invalid, improperly configured (e.g., incorrect API restrictions, required APIs not enabled), or the associated billing account is not set up.
fix
Obtain or verify your API key from the service provider's console (e.g., Google Cloud Console). Ensure the Geocoding API is enabled, the API key has the correct restrictions (e.g., IP address or HTTP referer), and a valid billing account is linked. Pass the API key to your geocoder call: `g = geocoder.google('address', key='YOUR_API_KEY')`.
Geocode was not successful: ZERO_RESULTS
The geocoding service could not find a matching geographic location for the provided address. This often happens when the address is too vague, misspelled, or lacks sufficient context (e.g., missing country for a common postal code).
fix
Refine your address query by providing more specific details, checking for typos, and including country or state information to reduce ambiguity. For example, instead of just a city name, include the state and country.
Upgrade
Version history
1.38.1latest on PyPI · released Apr 4, 2018
Audit
Dependencies
requestsrequiredUsed for making HTTP requests to external geocoding APIs.
ratelimoptionalFor rate limiting API calls to external geocoding services, preventing abuse and errors.
sixoptionalPython 2/3 compatibility layer, though less critical for modern Python 3-only environments.
clickoptionalPowers the command-line interface.
Agent activity
14 hits · last 30 days
node
12
Amazon
1
Resources
geocoder — pip install geocoder · libregistry