geocoder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Geocoder

Convert between addresses and geographic coordinates.

在地址与地理坐标之间进行转换。

Features

功能特性

Geocoding: Address to coordinates
Reverse Geocoding: Coordinates to address
Batch Processing: Process CSV files
Multiple Providers: Nominatim (free), Google, Bing
Address Components: Structured address parsing
Caching: Built-in result caching

地理编码：地址转坐标
逆地理编码：坐标转地址
批量处理：处理CSV文件
多服务商支持：Nominatim（免费）、Google、Bing
地址组件：结构化地址解析
缓存功能：内置结果缓存

Quick Start

快速开始

python

from geocoder import Geocoder

geo = Geocoder()

python

from geocoder import Geocoder

geo = Geocoder()

Address to coordinates

result = geo.geocode("1600 Amphitheatre Parkway, Mountain View, CA") print(f"Coordinates: {result['lat']}, {result['lon']}")

Coordinates to address

result = geo.reverse(37.4224, -122.0840) print(f"Address: {result['address']}")

undefined

result = geo.reverse(37.4224, -122.0840) print(f"Address: {result['address']}")

undefined

CLI Usage

CLI 用法

bash

undefined

bash

undefined

Geocode address

python geocoder.py --geocode "Empire State Building, New York"

Reverse geocode

python geocoder.py --reverse "40.7484,-73.9857"

Batch geocode CSV

python geocoder.py --input addresses.csv --column address --output geocoded.csv

Batch reverse geocode

python geocoder.py --input coords.csv --lat lat --lon lon --reverse-batch --output addresses.csv

undefined

python geocoder.py --input coords.csv --lat lat --lon lon --reverse-batch --output addresses.csv

undefined

API Reference

API 参考

Geocoder Class

Geocoder 类

python

class Geocoder:
    def __init__(self, provider: str = "nominatim", api_key: str = None)

    # Single operations
    def geocode(self, address: str) -> dict
    def reverse(self, lat: float, lon: float) -> dict

    # Batch operations
    def batch_geocode(self, addresses: list, delay: float = 1.0) -> list
    def batch_reverse(self, coordinates: list, delay: float = 1.0) -> list

    # File operations
    def geocode_csv(self, input: str, column: str, output: str) -> str
    def reverse_csv(self, input: str, lat: str, lon: str, output: str) -> str

python

class Geocoder:
    def __init__(self, provider: str = "nominatim", api_key: str = None)

    # Single operations
    def geocode(self, address: str) -> dict
    def reverse(self, lat: float, lon: float) -> dict

    # Batch operations
    def batch_geocode(self, addresses: list, delay: float = 1.0) -> list
    def batch_reverse(self, coordinates: list, delay: float = 1.0) -> list

    # File operations
    def geocode_csv(self, input: str, column: str, output: str) -> str
    def reverse_csv(self, input: str, lat: str, lon: str, output: str) -> str

Providers

服务商

Nominatim (Default)

Nominatim（默认）

Free, no API key required
Rate limited (1 request/second)
Uses OpenStreetMap data

免费，无需API密钥
有请求频率限制（每秒1次）
使用OpenStreetMap数据

Google Maps

python

geo = Geocoder(provider="google", api_key="YOUR_KEY")

python

geo = Geocoder(provider="google", api_key="YOUR_KEY")

Bing Maps

python

geo = Geocoder(provider="bing", api_key="YOUR_KEY")

python

geo = Geocoder(provider="bing", api_key="YOUR_KEY")

Geocoding Result

地理编码结果

python

{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA",
    "lat": 37.4224764,
    "lon": -122.0842499,
    "components": {
        "house_number": "1600",
        "road": "Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "California",
        "postcode": "94043",
        "country": "United States"
    },
    "raw": {...}  # Provider-specific data
}

python

{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA",
    "lat": 37.4224764,
    "lon": -122.0842499,
    "components": {
        "house_number": "1600",
        "road": "Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "California",
        "postcode": "94043",
        "country": "United States"
    },
    "raw": {...}  # Provider-specific data
}

Reverse Geocoding Result

逆地理编码结果

python

{
    "lat": 40.7484,
    "lon": -73.9857,
    "address": "20 W 34th St, New York, NY 10001, USA",
    "components": {
        "house_number": "20",
        "road": "West 34th Street",
        "city": "New York",
        "state": "New York",
        "postcode": "10001",
        "country": "United States"
    }
}

python

{
    "lat": 40.7484,
    "lon": -73.9857,
    "address": "20 W 34th St, New York, NY 10001, USA",
    "components": {
        "house_number": "20",
        "road": "West 34th Street",
        "city": "New York",
        "state": "New York",
        "postcode": "10001",
        "country": "United States"
    }
}

Example Workflows

示例工作流

Geocode Customer Addresses

地理编码客户地址

python

geo = Geocoder()
result = geo.geocode_csv(
    input="customers.csv",
    column="shipping_address",
    output="customers_geocoded.csv"
)
print(f"Geocoded {result['success']} of {result['total']} addresses")

python

geo = Geocoder()
result = geo.geocode_csv(
    input="customers.csv",
    column="shipping_address",
    output="customers_geocoded.csv"
)
print(f"Geocoded {result['success']} of {result['total']} addresses")

Validate Addresses

验证地址

python

geo = Geocoder()
address = "123 Main St, Anytown"

result = geo.geocode(address)
if result:
    print(f"Valid: {result['address']}")
    print(f"Standardized: {result['components']}")
else:
    print("Address not found")

python

geo = Geocoder()
address = "123 Main St, Anytown"

result = geo.geocode(address)
if result:
    print(f"Valid: {result['address']}")
    print(f"Standardized: {result['components']}")
else:
    print("Address not found")

Add Addresses to Coordinates

为坐标添加地址信息

python

geo = Geocoder()

locations = [
    (40.7128, -74.0060),
    (34.0522, -118.2437),
    (41.8781, -87.6298)
]

for lat, lon in locations:
    result = geo.reverse(lat, lon)
    print(f"({lat}, {lon}): {result['address']}")

python

geo = Geocoder()

locations = [
    (40.7128, -74.0060),
    (34.0522, -118.2437),
    (41.8781, -87.6298)
]

for lat, lon in locations:
    result = geo.reverse(lat, lon)
    print(f"({lat}, {lon}): {result['address']}")

Rate Limiting

请求频率限制

Nominatim requires 1 second between requests. The batch functions handle this automatically.

python

undefined

Nominatim要求请求间隔至少1秒。批量处理函数会自动处理这一限制。

python

undefined

Automatic delay in batch operations

results = geo.batch_geocode(addresses, delay=1.0)

For paid providers, can reduce delay

geo = Geocoder(provider="google", api_key="KEY") results = geo.batch_geocode(addresses, delay=0.1)

undefined

geo = Geocoder(provider="google", api_key="KEY") results = geo.batch_geocode(addresses, delay=0.1)

undefined

Error Handling

错误处理

python

result = geo.geocode("Invalid Address XYZ123")
if result is None:
    print("Address not found")
elif result.get('error'):
    print(f"Error: {result['error']}")
else:
    print(f"Found: {result['address']}")

python

result = geo.geocode("Invalid Address XYZ123")
if result is None:
    print("Address not found")
elif result.get('error'):
    print(f"Error: {result['error']}")
else:
    print(f"Found: {result['address']}")

Dependencies

依赖项

geopy>=2.4.0
pandas>=2.0.0

geopy>=2.4.0
pandas>=2.0.0