GeoPy Geocoding — Core Concepts

GeoPy is a Python library that provides a unified interface to dozens of geocoding services — Nominatim, Google, Bing, MapBox, and more. It abstracts away the HTTP calls, response parsing, and error handling so you can focus on the geographic logic.

Forward geocoding

Forward geocoding converts a text address into latitude/longitude coordinates:

from geopy.geocoders import Nominatim

geolocator = Nominatim(user_agent="my-app")
location = geolocator.geocode("221B Baker Street, London")

print(location.address)    # "221B Baker Street, Marylebone, London, ..."
print(location.latitude)   # 51.5237
print(location.longitude)  # -0.1585

The user_agent string identifies your application to the geocoding service. Nominatim (powered by OpenStreetMap) requires this and will block requests without it.

Reverse geocoding

Reverse geocoding takes coordinates and returns the nearest address:

location = geolocator.reverse("48.8584, 2.2945")
print(location.address)  # "Tour Eiffel, Avenue Anatole France, Paris, ..."

This is how ride-sharing apps display a street name when you drop a pin on the map.

Provider selection

Provider	Free tier	Rate limit	Strengths
Nominatim (OSM)	Unlimited (fair use)	1 req/sec	Free, global coverage, no API key
Google Maps	$200/month credit	50 req/sec	Best accuracy, structured results
MapBox	100K req/month	10 req/sec	Good for web map integration
Bing Maps	125K req/year	5 req/sec	Good coverage, Microsoft ecosystem
Photon	Unlimited (self-hosted)	No limit	Privacy-friendly, OSM data

For prototyping or small projects, Nominatim is the default choice. For production with thousands of daily lookups, Google or MapBox provide higher accuracy and structured address components.

Rate limiting

Geocoding services enforce rate limits. GeoPy provides a built-in adapter:

from geopy.extra.rate_limiter import RateLimiter

geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1.0)

# Now safe to use in a loop
addresses = ["Tokyo Tower", "Big Ben", "Statue of Liberty"]
locations = [geocode(addr) for addr in addresses]

Without rate limiting, you will get HTTP 429 errors or temporary bans. The RateLimiter wrapper handles delays automatically.

Distance calculations

GeoPy includes geodesic and great-circle distance functions:

from geopy.distance import geodesic

paris = (48.8566, 2.3522)
london = (51.5074, -0.1278)

distance = geodesic(paris, london)
print(distance.km)     # 343.56
print(distance.miles)  # 213.48

Geodesic distance uses the WGS-84 ellipsoid model and is accurate to within millimeters. Great-circle distance assumes a perfect sphere and is slightly less accurate but faster. For most applications, the difference is negligible.

Common misconception

Many developers assume geocoding returns a single, definitive result. In reality, most services return multiple candidates ranked by confidence. “Springfield” matches over 30 cities in the US alone. Always check the confidence score or provide additional context (state, country) to disambiguate.

Batch geocoding pattern

For large datasets, combine rate limiting with error handling:

import pandas as pd

df = pd.DataFrame({"address": ["Tokyo Tower", "Big Ben", "Colosseum"]})

geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1.0,
                      error_wait_seconds=5.0, max_retries=3)

df["location"] = df["address"].apply(geocode)
df["latitude"] = df["location"].apply(lambda loc: loc.latitude if loc else None)
df["longitude"] = df["location"].apply(lambda loc: loc.longitude if loc else None)

When geocoding is not enough

Geocoding gives you points. For questions like “What neighborhoods overlap with this delivery zone?” or “How far is this point from the nearest river?” you need geospatial analysis tools like Shapely and GeoPandas that work with shapes, not just points.

The one thing to remember: GeoPy makes geocoding provider-agnostic — swap between Nominatim, Google, and MapBox by changing one line, while the rate limiter keeps you from getting banned.