{"id":2957,"library":"geocoder","title":"Geocoder","description":"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.","status":"active","version":"1.38.1","language":"en","source_language":"en","source_url":"https://github.com/DenisCarriere/geocoder","tags":["geocoding","location","address lookup","reverse geocoding","geospatial"],"install":[{"cmd":"pip install geocoder","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to external geocoding APIs.","package":"requests"},{"reason":"For rate limiting API calls to external geocoding services, preventing abuse and errors.","package":"ratelim","optional":true},{"reason":"Python 2/3 compatibility layer, though less critical for modern Python 3-only environments.","package":"six","optional":true},{"reason":"Powers the command-line interface.","package":"click","optional":true}],"imports":[{"symbol":"geocoder","correct":"import geocoder"}],"quickstart":{"code":"import geocoder\nimport os\n\n# Geocoding an address using Google\n# An API key might be required for production use or higher quotas.\n# Set GOOGLE_API_KEY in your environment variables for security.\ngoogle_api_key = os.environ.get(\"GOOGLE_API_KEY\", \"\")\ng = geocoder.google(\"Mountain View, CA\", key=google_api_key)\n\nif g.ok:\n    print(f\"Google: Latitude: {g.latlng[0]}, Longitude: {g.latlng[1]}\")\n    print(f\"Address: {g.address}\")\nelse:\n    print(f\"Google Geocoding failed: {g.status}\")\n\n# Reverse geocoding using OpenStreetMap Nominatim (often no API key needed for basic use)\n# For production or heavy use with Nominatim, providing a unique 'user_agent' is recommended.\nn = geocoder.osm([37.38605, -122.08385]) # Coordinates for Apple Park\nif n.ok:\n    print(f\"\\nNominatim (Reverse): Address: {n.address}\")\nelse:\n    print(f\"Nominatim Reverse Geocoding failed: {n.status}\")\n\n# Example with a different provider (e.g., Mapbox), requiring an API key\nmapbox_api_key = os.environ.get(\"MAPBOX_API_KEY\", \"\")\nif mapbox_api_key:\n    m = geocoder.mapbox(\"San Francisco, CA\", key=mapbox_api_key)\n    if m.ok:\n        print(f\"\\nMapbox: Latitude: {m.latlng[0]}, Longitude: {m.latlng[1]}\")\n        print(f\"Address: {m.address}\")\n    else:\n        print(f\"Mapbox Geocoding failed: {m.status}\")\nelse:\n    print(\"\\nMAPBOX_API_KEY not set. Skipping Mapbox example.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"As 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.","severity":"breaking","affected_versions":">=1.6.0"},{"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.","message":"External 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}