tessl/pypi-geopy

Python Geocoding Toolbox providing comprehensive geocoding services and geodesic distance calculations

—

Pending

Overview

Eval results

Files

Geocoding Services

Name: tessl/pypi-geopy
Author: tessl

Geopy provides access to 31 geocoding services through a unified interface. Each geocoder implements common methods for forward and reverse geocoding while supporting service-specific parameters and options.

Capabilities

Common Geocoder Interface

All geocoders implement these standard methods with consistent parameter patterns and return types.

def geocode(query, exactly_one=True, timeout=None, **kwargs):
    """
    Forward geocoding - convert address to coordinates.
    
    Parameters:
    - query (str): Address or location to geocode
    - exactly_one (bool): Return single result (True) or list (False)
    - timeout (float): Request timeout in seconds
    - **kwargs: Service-specific parameters
    
    Returns:
    Location or List[Location] or None
    """

def reverse(query, exactly_one=True, timeout=None, **kwargs):
    """
    Reverse geocoding - convert coordinates to address.
    
    Parameters:
    - query (str or Point): Coordinates as "lat,lon" string or Point object
    - exactly_one (bool): Return single result (True) or list (False) 
    - timeout (float): Request timeout in seconds
    - **kwargs: Service-specific parameters
    
    Returns:
    Location or List[Location] or None
    """

Major Commercial Services

Google Geocoding API

Google's comprehensive geocoding service with global coverage and detailed results.

from geopy.geocoders import GoogleV3

class GoogleV3:
    def __init__(self, api_key=None, domain='maps.googleapis.com', 
                 scheme='https', client_id=None, secret_key=None,
                 user_agent=None, format_string=None, ssl_context=None,
                 adapter_factory=None, proxies=None):
        """
        Initialize Google Geocoding API client.
        
        Parameters:
        - api_key (str): Google API key
        - domain (str): API domain 
        - client_id (str): Google for Work client ID
        - secret_key (str): Google for Work secret key
        """
    
    def geocode(self, query, bounds=None, region=None, components=None, 
                place_id=None, language=None, sensor=False, **kwargs):
        """Google-specific geocoding parameters"""
    
    def reverse(self, query, result_type=None, location_type=None, 
                language=None, **kwargs):
        """Google-specific reverse geocoding parameters"""

Microsoft Bing Maps

Microsoft's geocoding service with strong coverage in North America and Europe.

from geopy.geocoders import Bing

class Bing:
    def __init__(self, api_key, format_string=None, scheme='https',
                 user_agent=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """
        Initialize Bing Maps Geocoding API client.
        
        Parameters:
        - api_key (str): Bing Maps API key (required)
        """
    
    def geocode(self, query, include_neighborhood=None, include_country_code=False,
                user_location=None, culture=None, **kwargs):
        """Bing-specific geocoding parameters"""
    
    def reverse(self, query, include_neighborhood=None, 
                include_country_code=False, culture=None, **kwargs):
        """Bing-specific reverse geocoding parameters"""

Here Geocoding API

HERE Technologies geocoding service with automotive-focused features.

from geopy.geocoders import Here, HereV7

class Here:
    def __init__(self, app_id=None, app_code=None, format_string=None,
                 scheme='https', user_agent=None, ssl_context=None,
                 adapter_factory=None, proxies=None):
        """Legacy HERE API (deprecated)"""

class HereV7:
    def __init__(self, apikey, format_string=None, scheme='https',
                 user_agent=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """
        Initialize HERE v7 Geocoding API client.
        
        Parameters:
        - apikey (str): HERE API key (required)
        """

Open Source / Free Services

OpenStreetMap Nominatim

Free geocoding service based on OpenStreetMap data with global coverage.

from geopy.geocoders import Nominatim

class Nominatim:
    def __init__(self, domain='nominatim.openstreetmap.org', scheme='https',
                 user_agent=None, format_string=None, view_box=None,
                 bounded=None, country_bias=None, ssl_context=None,
                 adapter_factory=None, proxies=None):
        """
        Initialize Nominatim geocoder.
        
        Parameters:
        - domain (str): Nominatim server domain
        - user_agent (str): Required user agent string
        - view_box (list): Preferred search bounding box
        - bounded (bool): Restrict search to view_box
        - country_bias (str): Country code for result biasing
        """
    
    def geocode(self, query, addressdetails=False, language=False,
                geometry=None, extratags=False, country_codes=None,
                viewbox=None, bounded=None, featuretype=None,
                namedetails=False, **kwargs):
        """Nominatim-specific geocoding parameters"""
    
    def reverse(self, query, addressdetails=True, language=False,
                zoom=18, **kwargs):
        """Nominatim-specific reverse geocoding parameters"""

Photon

Open source geocoding service based on OpenStreetMap data.

from geopy.geocoders import Photon

class Photon:
    def __init__(self, domain='photon.komoot.io', scheme='https',
                 user_agent=None, format_string=None, ssl_context=None,
                 adapter_factory=None, proxies=None):
        """
        Initialize Photon geocoder.
        
        Parameters:
        - domain (str): Photon server domain
        """
    
    def geocode(self, query, language=None, limit=None, osm_tag=None,
                lon=None, lat=None, **kwargs):
        """Photon-specific geocoding parameters"""
    
    def reverse(self, query, limit=None, **kwargs):
        """Photon-specific reverse geocoding parameters"""

Regional Services

China - Baidu Maps

Baidu's geocoding service for mainland China with local data coverage.

from geopy.geocoders import Baidu, BaiduV3

class Baidu:
    def __init__(self, api_key, scheme='https', user_agent=None,
                 format_string=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """Legacy Baidu API"""

class BaiduV3:
    def __init__(self, api_key, scheme='https', user_agent=None,
                 format_string=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """
        Initialize Baidu v3 Geocoding API client.
        
        Parameters:
        - api_key (str): Baidu API key (required)
        """

France - IGN and BAN

French national geocoding services for France-specific addresses.

from geopy.geocoders import IGNFrance, BANFrance

class IGNFrance:
    def __init__(self, api_key, username=None, password=None, referer=None,
                 domain='wxs.ign.fr', scheme='https', user_agent=None,
                 format_string=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """IGN France geocoding service"""

class BANFrance:
    def __init__(self, domain='api-adresse.data.gouv.fr', scheme='https',
                 user_agent=None, format_string=None, ssl_context=None,
                 adapter_factory=None, proxies=None):
        """Base Adresse Nationale (France) free geocoding service"""

Russia - Yandex

Yandex geocoding service with strong coverage in Russia and Eastern Europe.

from geopy.geocoders import Yandex

class Yandex:
    def __init__(self, api_key=None, lang=None, scheme='https',
                 user_agent=None, format_string=None, ssl_context=None,
                 adapter_factory=None, proxies=None):
        """
        Initialize Yandex Geocoding API client.
        
        Parameters:
        - api_key (str): Yandex API key
        - lang (str): Response language
        """

Specialized Services

What3Words

Global addressing system using three-word combinations for precise location identification.

from geopy.geocoders import What3Words, What3WordsV3

class What3Words:
    def __init__(self, api_key, scheme='https', format_string=None,
                 user_agent=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """Legacy What3Words API"""

class What3WordsV3:
    def __init__(self, api_key, scheme='https', format_string=None,
                 user_agent=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """
        Initialize What3Words v3 API client.
        
        Parameters:
        - api_key (str): What3Words API key (required)
        """
    
    def geocode(self, query, language='en', **kwargs):
        """Convert 3-word address to coordinates"""
    
    def reverse(self, query, language='en', **kwargs):
        """Convert coordinates to 3-word address"""

US-focused Services

Specialized geocoders optimized for United States addresses.

from geopy.geocoders import Geocodio, LiveAddress

class Geocodio:
    def __init__(self, api_key, scheme='https', format_string=None,
                 user_agent=None, ssl_context=None, adapter_factory=None,
                 proxies=None):
        """
        Geocodio - US and Canada focused geocoding.
        
        Parameters:
        - api_key (str): Geocodio API key (required)
        """

class LiveAddress:
    def __init__(self, auth_id, auth_token, candidates=1, scheme='https',
                 user_agent=None, format_string=None, ssl_context=None,
                 adapter_factory=None, proxies=None):
        """
        SmartyStreets LiveAddress API for US addresses.
        
        Parameters:
        - auth_id (str): SmartyStreets Auth ID
        - auth_token (str): SmartyStreets Auth Token
        - candidates (int): Maximum number of results
        """

Service Discovery

Utility function to get geocoder classes by service name.

from geopy.geocoders import get_geocoder_for_service

def get_geocoder_for_service(service):
    """
    Get geocoder class by service name string.
    
    Parameters:
    - service (str): Service name (e.g., 'nominatim', 'google', 'bing')
    
    Returns:
    Geocoder class
    
    Raises:
    GeocoderNotFound: If service name is not recognized
    """

Available Services

Complete list of available geocoder services:

ArcGIS - ESRI ArcGIS geocoding service
AzureMaps - Microsoft Azure Maps geocoding
Baidu / BaiduV3 - Baidu Maps geocoding (China)
BANFrance - Base Adresse Nationale (France)
Bing - Microsoft Bing Maps geocoding
DataBC - DataBC geocoding (British Columbia, Canada)
GeocodeEarth - Geocode.Earth service
Geocodio - Geocodio geocoding (US/Canada)
Geokeo - Geokeo geocoding service
GeoNames - GeoNames geocoding service
GoogleV3 - Google Geocoding API v3
Geolake - Geolake geocoding service
Here / HereV7 - HERE geocoding API
IGNFrance - IGN France geocoding
MapBox - Mapbox geocoding API
MapQuest - MapQuest geocoding API
MapTiler - MapTiler geocoding API
Nominatim - OpenStreetMap Nominatim
OpenCage - OpenCage geocoding API
OpenMapQuest - Open MapQuest geocoding
PickPoint - PickPoint geocoding service
Pelias - Pelias geocoding engine
Photon - Photon geocoding API
LiveAddress - SmartyStreets LiveAddress (US)
TomTom - TomTom geocoding API
What3Words / What3WordsV3 - What3Words API
Woosmap - Woosmap geocoding service
Yandex - Yandex geocoding (Russia)

Usage Examples

Basic Service Usage

from geopy.geocoders import Nominatim, GoogleV3, Bing

# Free service (rate limited)
geolocator = Nominatim(user_agent="my_app_name")
location = geolocator.geocode("New York City")

# Commercial services (require API keys)
google = GoogleV3(api_key="your_api_key")
bing = Bing(api_key="your_api_key")

location = google.geocode("1600 Amphitheatre Parkway, Mountain View, CA")
location = bing.geocode("Space Needle, Seattle, WA")

Service Selection

from geopy.geocoders import get_geocoder_for_service

# Dynamic service selection
service_name = "nominatim"  # Could come from config
geocoder_class = get_geocoder_for_service(service_name)
geolocator = geocoder_class(user_agent="my_app")

# Service comparison
services = ['nominatim', 'photon', 'opencage']
results = {}

for service in services:
    try:
        geocoder_class = get_geocoder_for_service(service)
        geolocator = geocoder_class(user_agent="comparison_app")
        results[service] = geolocator.geocode("Paris, France")
    except Exception as e:
        results[service] = str(e)

Language and Regional Parameters

# Language-specific results
nominatim = Nominatim(user_agent="my_app")
location_en = nominatim.geocode("London", language="en")  # English
location_fr = nominatim.geocode("London", language="fr")  # French
location_de = nominatim.geocode("London", language="de")  # German

# Regional biasing
google = GoogleV3(api_key="your_key")
location = google.geocode("Springfield", region="us")  # US bias
location = google.geocode("Springfield", region="uk")  # UK bias

# Country restrictions
nominatim.geocode("Paris", country_codes="fr")  # France only
nominatim.geocode("Paris", country_codes=["fr", "be"])  # France or Belgium

Install with Tessl CLI