or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async-support.mdcore-data-types.mddistance-calculations.mderror-handling.mdgeocoding-services.mdindex.mdrate-limiting.md
tile.json

tessl/pypi-geopy

Python Geocoding Toolbox providing comprehensive geocoding services and geodesic distance calculations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/geopy@2.4.x

To install, run

npx @tessl/cli install tessl/pypi-geopy@2.4.0

index.mddocs/

Geopy

A comprehensive Python client library for several popular geocoding web services that makes it easy for Python developers to locate coordinates of addresses, cities, countries, and landmarks across the globe using third-party geocoders and other data sources. Geopy provides both forward geocoding (address to coordinates) and reverse geocoding (coordinates to address) with a unified interface across multiple services, plus powerful geodesic distance calculation capabilities.

Package Information

  • Package Name: geopy
  • Language: Python
  • Installation: pip install geopy
  • Optional Dependencies:
    • pip install "geopy[aiohttp]" for async support
    • pip install "geopy[requests]" for requests adapter
    • pip install "geopy[timezone]" for timezone support

Core Imports

import geopy
from geopy.geocoders import Nominatim
from geopy import distance
from geopy.location import Location
from geopy.point import Point

Specific geocoder imports:

from geopy.geocoders import GoogleV3, Bing, ArcGIS, Here, MapBox
from geopy.geocoders import get_geocoder_for_service

Basic Usage

from geopy.geocoders import Nominatim
from geopy.distance import geodesic

# Initialize a geocoder
geolocator = Nominatim(user_agent="specify_your_app_name_here")

# Forward geocoding - address to coordinates
location = geolocator.geocode("175 5th Avenue NYC")
print(location.address)
print((location.latitude, location.longitude))

# Reverse geocoding - coordinates to address
location = geolocator.reverse("52.509669, 13.376294")
print(location.address)

# Distance calculation
newport_ri = (41.49008, -71.312796)
cleveland_oh = (41.499498, -81.695391)
distance = geodesic(newport_ri, cleveland_oh).miles
print(f"Distance: {distance} miles")

Architecture

Geopy's architecture is built around three core concepts:

  • Geocoders: Service-specific classes that abstract geocoding APIs with unified interfaces
  • Data Classes: Location, Point, and Timezone objects that represent geographical data
  • Distance Calculations: Geodesic and great-circle algorithms for precise distance measurements
  • Adapters: HTTP client abstraction supporting both synchronous and asynchronous operations

This design enables consistent geocoding across 31 different services while providing flexible configuration, comprehensive error handling, and support for both sync and async operations.

Capabilities

Geocoding Services

Access to 31 geocoding services including Google, Bing, OpenStreetMap Nominatim, Here, and many others. Each geocoder provides forward and reverse geocoding with service-specific options and configurations.

# Common geocoder interface
def geocode(query, exactly_one=True, timeout=None, **kwargs):
    """Forward geocoding - address to coordinates"""

def reverse(query, exactly_one=True, timeout=None, **kwargs):
    """Reverse geocoding - coordinates to address"""

Geocoding Services

Core Data Types

Essential data structures for representing locations, coordinates, and geographical points with comprehensive parsing and formatting capabilities.

class Location:
    """Parsed geocoder response with address and coordinates"""
    address: str
    latitude: float
    longitude: float
    point: Point
    raw: dict

class Point:
    """Geodetic point with latitude, longitude, and altitude"""
    def __init__(self, latitude, longitude, altitude=None): ...
    latitude: float
    longitude: float
    altitude: float

Core Data Types

Distance Calculations

Precise distance calculations using geodesic (ellipsoidal earth model) and great-circle (spherical earth model) algorithms with automatic unit conversions and destination point calculations.

class geodesic:
    """Geodesic distance using ellipsoidal earth model"""
    def __init__(point1, point2, ellipsoid='WGS-84'): ...
    kilometers: float
    miles: float
    meters: float
    
def destination(point, bearing, distance=None):
    """Calculate destination point from bearing and distance"""

Distance Calculations

Error Handling

Comprehensive exception hierarchy covering authentication failures, quota exceeded, rate limiting, service unavailability, and parsing errors with detailed error information.

class GeopyError(Exception):
    """Base exception for all geopy errors"""

class GeocoderServiceError(GeopyError):
    """Generic geocoding service error"""

class GeocoderRateLimited(GeocoderServiceError):
    """Rate limiting error with retry_after attribute"""
    retry_after: int

Error Handling

Async Support

Asynchronous geocoding operations using aiohttp adapter for high-performance applications requiring concurrent geocoding requests.

from geopy.adapters import AioHTTPAdapter

async with Nominatim(
    user_agent="specify_your_app_name_here",
    adapter_factory=AioHTTPAdapter,
) as geolocator:
    location = await geolocator.geocode("175 5th Avenue NYC")

Async Support

Rate Limiting

Built-in rate limiting functionality to manage API quotas and prevent service abuse with configurable delays, retry logic, and error handling.

from geopy.extra.rate_limiter import RateLimiter

geocoder = RateLimiter(
    geolocator.geocode, 
    min_delay_seconds=1.0,
    max_retries=2
)

Rate Limiting

Types

from typing import Union, Optional, List, Dict, Any, Tuple

# Common type aliases used throughout geopy
LocationType = Union[Location, None]
LocationListType = Union[List[Location], LocationType]
PointType = Union[Point, str, Tuple[float, float], Tuple[float, float, float]]
CoordinatePair = Tuple[float, float]