geopy

library2.5.0pypypi✓ verified 26d ago

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.

http-networking data serialization

pip install geopy

github ↗package ↗

INSTALL

IMPORT

SIG · GEOPY

geopy

http-networkingpythonv2.5.0

Install

1.7s avg

Import

354ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.5.0 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.372s · 19MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.336s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

Nominatim

✓ from geopy.geocoders import Nominatim

geodesic

✓ from geopy.distance import geodesic

Location

✓ from geopy.location import Location

Point

✓ from geopy.point import Point

✗ Point(40.7410861)

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).

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.

import os from geopy.geocoders import Nominatim # For Nominatim, a 'user_agent' is required. # In a production environment, use a unique, descriptive string for your application. geolocator = Nominatim(user_agent=os.environ.get('GEOPY_USER_AGENT', 'my_geocoding_app')) # Geocode an address address = "175 5th Avenue NYC" location = geolocator.geocode(address) if location: print(f"Address: {location.address}") print(f"Latitude: {location.latitude}, Longitude: {location.longitude}") else: print(f"Could not find location for: {address}") # Reverse geocode coordinates coordinates = "52.509669, 13.376294" # Berlin reversed_location = geolocator.reverse(coordinates) if reversed_location: print(f"\nCoordinates: {coordinates}") print(f"Address: {reversed_location.address}") else: print(f"Could not find address for: {coordinates}")

Debug

Known issues

breakingThe `geopy.distance.vincenty` algorithm was removed in geopy 2.0.0. It should be replaced with `geopy.distance.geodesic` for accurate distance calculations.

fix

Replace `from geopy.distance import vincenty` with `from geopy.distance import geodesic` and update calls accordingly.

affects: >=2.0.0

breakingIn 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.

fix

If you require multiple results, explicitly set `exactly_one=False` in your `geocode` or `reverse` calls.

affects: >=2.0.0

breakingService-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.

fix

Move any service-specific parameters from the geocoder's constructor to the `geocode` or `reverse` method calls.

affects: >=2.0.0

breakingThe `Algolia Places` geocoder was removed in geopy 2.4.0 because the underlying service was shut down.

fix

Migrate to an alternative geocoding service supported by geopy, such as Nominatim, GoogleV3, or MapBox.

affects: >=2.4.0

gotchaThe `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.

fix

Always provide a unique and descriptive `user_agent` when initializing `Nominatim`, e.g., `Nominatim(user_agent='my_awesome_app_name')`.

affects: All versions

gotchaThe `GoogleV3` geocoder changed its behavior in geopy 2.1.0: a missing `api_key` now raises an error instead of a warning.

fix

Ensure an `api_key` is always provided when initializing `GoogleV3` to avoid runtime errors.

affects: >=2.1.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'geopy'

The 'geopy' package is not installed in the Python environment being used, or a local file named 'geopy.py' is shadowing the installed package.

fix

Install the package using `pip install geopy`. If the issue persists, rename any local Python files named `geopy.py` or ensure you are in the correct virtual environment where geopy is installed.

ModuleNotFoundError: No module named 'geopy.geocoders'; 'geopy' is not a package

This specific ModuleNotFoundError typically occurs when a user-created Python file or directory is named 'geopy.py' or 'geopy', conflicting with the actual installed 'geopy' package during an import like `from geopy.geocoders import Nominatim`.

fix

Rename any local Python files or directories named `geopy.py` or `geopy` to avoid conflict with the installed library.

AttributeError: 'NoneType' object has no attribute 'latitude'

The `geocode()` or `reverse()` method returned `None` because it could not find a matching location for the given query, and the code then attempted to access attributes like `latitude`, `longitude`, or `address` on this `None` object.

fix

Always check if the `location` object returned by `geocode()` or `reverse()` is `None` before attempting to access its attributes. For example: `location = geolocator.geocode('NonExistent Address')` then `if location: print(location.latitude)`.

geopy.exc.GeocoderTimedOut: Service timed out

The geocoding service did not respond within the default or specified timeout period, often due to slow network connections, an overloaded service, or transient issues with the geocoding provider.

fix

Increase the `timeout` parameter when initializing the geolocator or when calling `geocode`/`reverse`. For example: `geolocator = Nominatim(user_agent='my-app', timeout=10)` or `location = geolocator.geocode(query, timeout=10)`.

geopy.exc.GeocoderServiceError: HTTP Error 429: Too Many Requests

The geocoding service rejected the request because the application exceeded the allowed rate limits (too many requests in a given time period) imposed by the service provider.

fix

Implement rate-limiting (e.g., using `time.sleep()` between requests or `geopy.extra.rate_limiter`), introduce delays between API calls, or consider upgrading to a paid plan with higher request quotas from the geocoding service provider.

Upgrade

Version history

2.5.0latest on PyPI · released Jul 12, 2026

Audit

Dependencies

geographiclibrequiredRequired for geodesic distance calculations.

requestsoptionalUsed by default for HTTP requests if installed (RequestsAdapter).

aiohttpoptionalRequired for asynchronous HTTP support (AioHTTPAdapter).

pytzoptionalFor timezone support.

Agent activity

8 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/geopy/geopy ↗

packagehttps://pypi.org/project/geopy/ ↗