CSV2GEO Python SDK

Official Python SDK for the CSV2GEO Geocoding API - fast, accurate geocoding powered by 461M+ addresses worldwide.

Installation

pip install csv2geo

Quick Start

from csv2geo import Client

# Initialize with your API key
client = Client("your_api_key")

# Forward geocoding (address → coordinates)
result = client.geocode("1600 Pennsylvania Ave, Washington DC")
if result:
    print(f"Lat: {result.lat}, Lng: {result.lng}")
    print(f"Address: {result.formatted_address}")

# Reverse geocoding (coordinates → address)
result = client.reverse(38.8977, -77.0365)
if result:
    print(f"Address: {result.formatted_address}")

Features

• Forward geocoding - Convert addresses to coordinates
• Reverse geocoding - Convert coordinates to addresses
• Batch processing - Geocode up to 10,000 addresses per request
• Auto-retry - Automatic retry on rate limits
• Type hints - Full type annotations for IDE support

API Reference

Initialize Client

from csv2geo import Client

client = Client(
    api_key="your_api_key",
    base_url="https://csv2geo.com/api/v1",  # optional
    timeout=30,  # optional, seconds
    auto_retry=True,  # optional, retry on rate limit
)

Forward Geocoding

# Simple - returns best match or None
result = client.geocode("1600 Pennsylvania Ave, Washington DC")

# With country filter
result = client.geocode("123 Main St", country="US")

# Full response with all matches
response = client.geocode_full("1600 Pennsylvania Ave")
for result in response.results:
    print(f"{result.formatted_address}: {result.accuracy_score}")

Reverse Geocoding

# Simple - returns best match or None
result = client.reverse(38.8977, -77.0365)

# Full response with all matches
response = client.reverse_full(38.8977, -77.0365)

Batch Geocoding

# Geocode multiple addresses (up to 10,000)
addresses = [
    "1600 Pennsylvania Ave, Washington DC",
    "350 Fifth Avenue, New York, NY",
    "1 Infinite Loop, Cupertino, CA",
]

results = client.geocode_batch(addresses)
for response in results:
    if response.best:
        print(f"{response.query}: {response.best.lat}, {response.best.lng}")
    else:
        print(f"{response.query}: Not found")

Batch Reverse Geocoding

# Reverse geocode multiple coordinates
coordinates = [
    (38.8977, -77.0365),
    (40.7484, -73.9857),
]

results = client.reverse_batch(coordinates)
for response in results:
    if response.best:
        print(response.best.formatted_address)

Normalize addresses (USPS Pub 28, parse-only)

out = client.normalize_batch([
    {"id": "1", "address": "123 Stewart Street Northwest", "city": "Huntsville", "state": "Alabama", "zip": "35801"},
    "309 S W Stewart Hwy, Columbus OH 43215",
])
for r in out["results"]:
    print(r["ok"], r["formatted"], r["changes"], r.get("reason"))
# True 123 STEWART ST NW, HUNTSVILLE AL 35801 [...]
single = client.normalize("123 Stewart Street Northwest, Huntsville AL 35801")["result"]

Up to 1,000 addresses per call. No geocoding happens; directionals are returned as N S E W NE NW SE SW.

GeocodeResult Object

result = client.geocode("1600 Pennsylvania Ave, Washington DC")

# Coordinates
result.lat           # 38.8977
result.lng           # -77.0365
result.location      # Location(lat=38.8977, lng=-77.0365)

# Address
result.formatted_address  # "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC 20500, US"
result.accuracy           # "rooftop"
result.accuracy_score     # 1.0

# Components
result.components.house_number  # "1600"
result.components.street        # "PENNSYLVANIA AVE NW"
result.components.city          # "WASHINGTON"
result.components.state         # "DC"
result.components.postcode      # "20500"
result.components.country       # "US"

Error Handling

from csv2geo import Client, AuthenticationError, RateLimitError, InvalidRequestError

client = Client("your_api_key")

try:
    result = client.geocode("123 Main St")
except AuthenticationError as e:
    print(f"Invalid API key: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except InvalidRequestError as e:
    print(f"Invalid request: {e.message}")

Rate Limits

The client tracks rate limit headers automatically:

client.geocode("123 Main St")

print(client.rate_limit)            # Max requests per minute
print(client.rate_limit_remaining)  # Requests remaining
print(client.rate_limit_reset)      # Unix timestamp when limit resets

With auto_retry=True (default), the client automatically waits and retries when rate limited.

Context Manager

with Client("your_api_key") as client:
    result = client.geocode("123 Main St")
    print(result.lat, result.lng)
# Session automatically closed

Get Your API Key

Sign up at csv2geo.com to get your API key.

Documentation

• API Documentation
• OpenAPI Specification

Community & Support

• Questions & feature requests: GitHub Discussions
• Bug reports: GitHub Issues

License

MIT License - see LICENSE for details.