{"library":"geopy","title":"geopy","description":"geopy is a Python client for numerous popular geocoding web services, including OpenStreetMap Nominatim, Google Geocoding API, and Bing Maps. It simplifies the process for Python developers to locate the coordinates of addresses, cities, countries, and landmarks globally, as well as perform reverse geocoding. The library is actively maintained, with its current stable version being 2.4.1, and releases occur regularly to add features and address issues. It supports Python versions 3.7 through 3.12.","status":"active","version":"2.4.1","language":"en","source_language":"en","source_url":"https://github.com/geopy/geopy","tags":["geocoding","location","maps","reverse-geocoding","distance"],"install":[{"cmd":"pip install geopy","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Required for geodesic distance calculations.","package":"geographiclib","optional":false},{"reason":"Used by default for HTTP requests if installed (RequestsAdapter).","package":"requests","optional":true},{"reason":"Required for asynchronous HTTP support (AioHTTPAdapter).","package":"aiohttp","optional":true},{"reason":"For timezone support.","package":"pytz","optional":true}],"imports":[{"symbol":"Nominatim","correct":"from geopy.geocoders import Nominatim"},{"symbol":"geodesic","correct":"from geopy.distance import geodesic"},{"symbol":"Location","correct":"from geopy.location import Location"},{"note":"As of geopy 2.0.0, constructing a Point from a single number raises a ValueError; longitude must be explicitly passed, e.g., Point(40.7410861, 0).","wrong":"Point(40.7410861)","symbol":"Point","correct":"from geopy.point import Point"}],"quickstart":{"code":"import os\nfrom geopy.geocoders import Nominatim\n\n# For Nominatim, a 'user_agent' is required.\n# In a production environment, use a unique, descriptive string for your application.\ngeolocator = Nominatim(user_agent=os.environ.get('GEOPY_USER_AGENT', 'my_geocoding_app'))\n\n# Geocode an address\naddress = \"175 5th Avenue NYC\"\nlocation = geolocator.geocode(address)\n\nif location:\n    print(f\"Address: {location.address}\")\n    print(f\"Latitude: {location.latitude}, Longitude: {location.longitude}\")\nelse:\n    print(f\"Could not find location for: {address}\")\n\n# Reverse geocode coordinates\ncoordinates = \"52.509669, 13.376294\" # Berlin\nreversed_location = geolocator.reverse(coordinates)\n\nif reversed_location:\n    print(f\"\\nCoordinates: {coordinates}\")\n    print(f\"Address: {reversed_location.address}\")\nelse:\n    print(f\"Could not find address for: {coordinates}\")","lang":"python","description":"This quickstart demonstrates how to use the Nominatim geocoder to convert an address string into geographical coordinates (latitude and longitude) and vice-versa. It highlights the necessity of providing a `user_agent` for Nominatim, as recommended by its usage policy, and safely retrieves it from an environment variable."},"warnings":[{"fix":"Replace `from geopy.distance import vincenty` with `from geopy.distance import geodesic` and update calls accordingly.","message":"The `geopy.distance.vincenty` algorithm was removed in geopy 2.0.0. It should be replaced with `geopy.distance.geodesic` for accurate distance calculations.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If you require multiple results, explicitly set `exactly_one=False` in your `geocode` or `reverse` calls.","message":"In geopy 2.0.0, the default for the `exactly_one` parameter in geocoders' `geocode` and `reverse` methods changed to `True`. This means methods will return a single `Location` object (or `None`) by default, rather than a list.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Move any service-specific parameters from the geocoder's constructor to the `geocode` or `reverse` method calls.","message":"Service-specific request parameters are no longer accepted in the `__init__` methods of geocoder classes as of geopy 2.0.0. They must now be passed directly to the corresponding `geocode` or `reverse` methods.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate to an alternative geocoding service supported by geopy, such as Nominatim, GoogleV3, or MapBox.","message":"The `Algolia Places` geocoder was removed in geopy 2.4.0 because the underlying service was shut down.","severity":"breaking","affected_versions":">=2.4.0"},{"fix":"Always provide a unique and descriptive `user_agent` when initializing `Nominatim`, e.g., `Nominatim(user_agent='my_awesome_app_name')`.","message":"The `Nominatim` geocoder (OpenStreetMap) requires a `user_agent` string in its constructor to identify your application. Failing to provide one may result in `ConfigurationError` or service blocking.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure an `api_key` is always provided when initializing `GoogleV3` to avoid runtime errors.","message":"The `GoogleV3` geocoder changed its behavior in geopy 2.1.0: a missing `api_key` now raises an error instead of a warning.","severity":"gotcha","affected_versions":">=2.1.0"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}