csv2geo 1.0.0__py3-none-any.whl

csv2geo/__init__.py

@@ -0,0 +1,35 @@
+"""
+CSV2GEO Python SDK
+
+Fast, accurate geocoding powered by 446M+ addresses worldwide.
+
+Usage:
+    from csv2geo import Client
+
+    client = Client("your_api_key")
+    result = client.geocode("1600 Pennsylvania Ave, Washington DC")
+    print(result.lat, result.lng)
+"""
+
+from .client import Client
+from .models import GeocodeResult, Location, AddressComponents
+from .exceptions import (
+    CSV2GEOError,
+    AuthenticationError,
+    RateLimitError,
+    InvalidRequestError,
+    APIError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "Client",
+    "GeocodeResult",
+    "Location",
+    "AddressComponents",
+    "CSV2GEOError",
+    "AuthenticationError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "APIError",
+]

csv2geo/client.py

@@ -0,0 +1,328 @@
+"""CSV2GEO API Client."""
+
+import time
+from typing import List, Optional, Union, Tuple
+import requests
+
+from .models import GeocodeResult, GeocodeResponse, BatchGeocodeResponse, Location
+from .exceptions import (
+    CSV2GEOError,
+    AuthenticationError,
+    RateLimitError,
+    InvalidRequestError,
+    PermissionError,
+    APIError,
+)
+
+
+class Client:
+    """
+    CSV2GEO API Client.
+
+    Usage:
+        client = Client("your_api_key")
+
+        # Forward geocoding
+        result = client.geocode("1600 Pennsylvania Ave, Washington DC")
+        print(result.lat, result.lng)
+
+        # Reverse geocoding
+        result = client.reverse(38.8977, -77.0365)
+        print(result.formatted_address)
+
+        # Batch geocoding
+        results = client.geocode_batch([
+            "1600 Pennsylvania Ave, Washington DC",
+            "350 Fifth Avenue, New York, NY",
+        ])
+        for r in results:
+            print(r.best.formatted_address if r.best else "Not found")
+    """
+
+    DEFAULT_BASE_URL = "https://api.csv2geo.com/v1"
+    DEFAULT_TIMEOUT = 30
+    MAX_RETRIES = 3
+    RETRY_DELAY = 1  # seconds
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = None,
+        timeout: int = None,
+        auto_retry: bool = True,
+    ):
+        """
+        Initialize the CSV2GEO client.
+
+        Args:
+            api_key: Your CSV2GEO API key
+            base_url: API base URL (default: https://api.csv2geo.com/v1)
+            timeout: Request timeout in seconds (default: 30)
+            auto_retry: Automatically retry on rate limit (default: True)
+        """
+        if not api_key:
+            raise ValueError("API key is required")
+
+        self.api_key = api_key
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout or self.DEFAULT_TIMEOUT
+        self.auto_retry = auto_retry
+
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": "csv2geo-python/1.0.0",
+            "Content-Type": "application/json",
+        })
+
+        # Rate limit tracking
+        self.rate_limit = None
+        self.rate_limit_remaining = None
+        self.rate_limit_reset = None
+
+    def _handle_response(self, response: requests.Response) -> dict:
+        """Handle API response and raise appropriate exceptions."""
+        # Update rate limit info from headers
+        self.rate_limit = response.headers.get("X-RateLimit-Limit")
+        self.rate_limit_remaining = response.headers.get("X-RateLimit-Remaining")
+        self.rate_limit_reset = response.headers.get("X-RateLimit-Reset")
+
+        if response.status_code == 200:
+            return response.json()
+
+        # Handle errors
+        try:
+            error_data = response.json().get("error", {})
+            code = error_data.get("code", "unknown")
+            message = error_data.get("message", "Unknown error")
+            status = error_data.get("status", response.status_code)
+        except (ValueError, KeyError):
+            code = "unknown"
+            message = response.text or "Unknown error"
+            status = response.status_code
+
+        if response.status_code == 401:
+            raise AuthenticationError(message, code=code, status=status)
+        elif response.status_code == 403:
+            raise PermissionError(message, code=code, status=status)
+        elif response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", 60))
+            raise RateLimitError(
+                message, code=code, status=status, retry_after=retry_after
+            )
+        elif response.status_code == 400:
+            raise InvalidRequestError(message, code=code, status=status)
+        else:
+            raise APIError(message, code=code, status=status)
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict = None,
+        json: dict = None,
+        retry_count: int = 0,
+    ) -> dict:
+        """Make an API request with retry logic."""
+        url = f"{self.base_url}{endpoint}"
+
+        try:
+            response = self._session.request(
+                method=method,
+                url=url,
+                params=params,
+                json=json,
+                timeout=self.timeout,
+            )
+            return self._handle_response(response)
+
+        except RateLimitError as e:
+            if self.auto_retry and retry_count < self.MAX_RETRIES:
+                wait_time = min(e.retry_after or self.RETRY_DELAY, 60)
+                time.sleep(wait_time)
+                return self._request(
+                    method, endpoint, params, json, retry_count + 1
+                )
+            raise
+
+        except requests.exceptions.Timeout:
+            raise APIError("Request timed out", code="timeout")
+        except requests.exceptions.ConnectionError:
+            raise APIError("Connection failed", code="connection_error")
+
+    def geocode(
+        self,
+        address: str,
+        country: str = None,
+    ) -> Optional[GeocodeResult]:
+        """
+        Geocode a single address.
+
+        Args:
+            address: The address to geocode
+            country: Limit results to a specific country (ISO 3166-1 alpha-2)
+
+        Returns:
+            GeocodeResult or None if not found
+
+        Example:
+            result = client.geocode("1600 Pennsylvania Ave, Washington DC")
+            if result:
+                print(f"Lat: {result.lat}, Lng: {result.lng}")
+        """
+        params = {"q": address}
+        if country:
+            params["country"] = country
+
+        data = self._request("GET", "/geocode", params=params)
+        response = GeocodeResponse.from_dict(data)
+        return response.best
+
+    def geocode_full(
+        self,
+        address: str,
+        country: str = None,
+    ) -> GeocodeResponse:
+        """
+        Geocode a single address and return full response with all results.
+
+        Args:
+            address: The address to geocode
+            country: Limit results to a specific country (ISO 3166-1 alpha-2)
+
+        Returns:
+            GeocodeResponse with all matching results
+        """
+        params = {"q": address}
+        if country:
+            params["country"] = country
+
+        data = self._request("GET", "/geocode", params=params)
+        return GeocodeResponse.from_dict(data)
+
+    def reverse(
+        self,
+        lat: float,
+        lng: float,
+    ) -> Optional[GeocodeResult]:
+        """
+        Reverse geocode coordinates to an address.
+
+        Args:
+            lat: Latitude
+            lng: Longitude
+
+        Returns:
+            GeocodeResult or None if not found
+
+        Example:
+            result = client.reverse(38.8977, -77.0365)
+            if result:
+                print(result.formatted_address)
+        """
+        params = {"lat": lat, "lng": lng}
+        data = self._request("GET", "/reverse", params=params)
+        response = GeocodeResponse.from_dict(data)
+        return response.best
+
+    def reverse_full(
+        self,
+        lat: float,
+        lng: float,
+    ) -> GeocodeResponse:
+        """
+        Reverse geocode coordinates and return full response.
+
+        Args:
+            lat: Latitude
+            lng: Longitude
+
+        Returns:
+            GeocodeResponse with all matching results
+        """
+        params = {"lat": lat, "lng": lng}
+        data = self._request("GET", "/reverse", params=params)
+        return GeocodeResponse.from_dict(data)
+
+    def geocode_batch(
+        self,
+        addresses: List[str],
+    ) -> List[GeocodeResponse]:
+        """
+        Geocode multiple addresses in a single request.
+
+        Args:
+            addresses: List of addresses to geocode (max 10,000)
+
+        Returns:
+            List of GeocodeResponse objects
+
+        Example:
+            results = client.geocode_batch([
+                "1600 Pennsylvania Ave, Washington DC",
+                "350 Fifth Avenue, New York, NY",
+            ])
+            for r in results:
+                if r.best:
+                    print(f"{r.query}: {r.best.lat}, {r.best.lng}")
+        """
+        if len(addresses) > 10000:
+            raise InvalidRequestError("Maximum 10,000 addresses per batch request")
+
+        data = self._request("POST", "/geocode", json={"addresses": addresses})
+        response = BatchGeocodeResponse.from_dict(data)
+        return response.results
+
+    def reverse_batch(
+        self,
+        coordinates: List[Union[Tuple[float, float], Location, dict]],
+    ) -> List[GeocodeResponse]:
+        """
+        Reverse geocode multiple coordinates in a single request.
+
+        Args:
+            coordinates: List of coordinates as (lat, lng) tuples, Location objects,
+                        or dicts with 'lat' and 'lng' keys (max 10,000)
+
+        Returns:
+            List of GeocodeResponse objects
+
+        Example:
+            results = client.reverse_batch([
+                (38.8977, -77.0365),
+                (40.7484, -73.9857),
+            ])
+            for r in results:
+                if r.best:
+                    print(r.best.formatted_address)
+        """
+        if len(coordinates) > 10000:
+            raise InvalidRequestError("Maximum 10,000 coordinates per batch request")
+
+        # Normalize coordinates to dict format
+        coords_list = []
+        for coord in coordinates:
+            if isinstance(coord, tuple):
+                coords_list.append({"lat": coord[0], "lng": coord[1]})
+            elif isinstance(coord, Location):
+                coords_list.append(coord.to_dict())
+            elif isinstance(coord, dict):
+                coords_list.append(coord)
+            else:
+                raise InvalidRequestError(
+                    f"Invalid coordinate format: {type(coord)}"
+                )
+
+        data = self._request("POST", "/reverse", json={"coordinates": coords_list})
+        response = BatchGeocodeResponse.from_dict(data)
+        return response.results
+
+    def close(self):
+        """Close the client session."""
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

csv2geo/exceptions.py

@@ -0,0 +1,39 @@
+"""Custom exceptions for CSV2GEO SDK."""
+
+
+class CSV2GEOError(Exception):
+    """Base exception for CSV2GEO SDK."""
+
+    def __init__(self, message: str, code: str = None, status: int = None):
+        self.message = message
+        self.code = code
+        self.status = status
+        super().__init__(self.message)
+
+
+class AuthenticationError(CSV2GEOError):
+    """Raised when API key is missing, invalid, or revoked."""
+    pass
+
+
+class RateLimitError(CSV2GEOError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str, retry_after: int = None, **kwargs):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class InvalidRequestError(CSV2GEOError):
+    """Raised when request parameters are invalid."""
+    pass
+
+
+class PermissionError(CSV2GEOError):
+    """Raised when API key lacks required permission."""
+    pass
+
+
+class APIError(CSV2GEOError):
+    """Raised for general API errors."""
+    pass

csv2geo/models.py

@@ -0,0 +1,123 @@
+"""Data models for CSV2GEO API responses."""
+
+from dataclasses import dataclass
+from typing import Optional, List
+
+
+@dataclass
+class Location:
+    """Geographic coordinates."""
+    lat: float
+    lng: float
+
+    def __str__(self) -> str:
+        return f"{self.lat}, {self.lng}"
+
+    def to_dict(self) -> dict:
+        return {"lat": self.lat, "lng": self.lng}
+
+
+@dataclass
+class AddressComponents:
+    """Parsed address components."""
+    house_number: Optional[str] = None
+    street: Optional[str] = None
+    unit: Optional[str] = None
+    city: Optional[str] = None
+    state: Optional[str] = None
+    postcode: Optional[str] = None
+    country: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AddressComponents":
+        return cls(
+            house_number=data.get("house_number"),
+            street=data.get("street"),
+            unit=data.get("unit"),
+            city=data.get("city"),
+            state=data.get("state"),
+            postcode=data.get("postcode"),
+            country=data.get("country"),
+        )
+
+
+@dataclass
+class GeocodeResult:
+    """A single geocoding result."""
+    formatted_address: str
+    lat: float
+    lng: float
+    accuracy: str
+    accuracy_score: float
+    components: AddressComponents
+
+    @property
+    def location(self) -> Location:
+        """Get location as a Location object."""
+        return Location(lat=self.lat, lng=self.lng)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "GeocodeResult":
+        location = data.get("location", {})
+        return cls(
+            formatted_address=data.get("formatted_address", ""),
+            lat=location.get("lat", 0.0),
+            lng=location.get("lng", 0.0),
+            accuracy=data.get("accuracy", ""),
+            accuracy_score=data.get("accuracy_score", 0.0),
+            components=AddressComponents.from_dict(data.get("components", {})),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "formatted_address": self.formatted_address,
+            "location": {"lat": self.lat, "lng": self.lng},
+            "accuracy": self.accuracy,
+            "accuracy_score": self.accuracy_score,
+        }
+
+
+@dataclass
+class GeocodeResponse:
+    """Response from a geocode request."""
+    query: str
+    results: List[GeocodeResult]
+
+    @property
+    def best(self) -> Optional[GeocodeResult]:
+        """Get the best (first) result, or None if no results."""
+        return self.results[0] if self.results else None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "GeocodeResponse":
+        results = [
+            GeocodeResult.from_dict(r)
+            for r in data.get("results", [])
+        ]
+        return cls(
+            query=data.get("query", ""),
+            results=results,
+        )
+
+
+@dataclass
+class BatchGeocodeResponse:
+    """Response from a batch geocode request."""
+    results: List[GeocodeResponse]
+    total: int
+    successful: int
+    failed: int
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "BatchGeocodeResponse":
+        meta = data.get("meta", {})
+        results = [
+            GeocodeResponse.from_dict(r)
+            for r in data.get("results", [])
+        ]
+        return cls(
+            results=results,
+            total=meta.get("total", len(results)),
+            successful=meta.get("successful", len(results)),
+            failed=meta.get("failed", 0),
+        )

csv2geo-1.0.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: csv2geo
+Version: 1.0.0
+Summary: Python SDK for CSV2GEO Geocoding API
+Author-email: Scale Campaign <admin@csv2geo.com>
+License: MIT
+Project-URL: Homepage, https://csv2geo.com
+Project-URL: Documentation, https://acenji.github.io/csv2geo-api/docs/
+Project-URL: Repository, https://github.com/acenji/csv2geo-api
+Project-URL: Issues, https://github.com/acenji/csv2geo-api/issues
+Keywords: geocoding,geocode,address,latitude,longitude,maps,csv2geo
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+
+# CSV2GEO Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/csv2geo.svg)](https://pypi.org/project/csv2geo/)
+[![Python versions](https://img.shields.io/pypi/pyversions/csv2geo.svg)](https://pypi.org/project/csv2geo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official Python SDK for the [CSV2GEO Geocoding API](https://csv2geo.com) - fast, accurate geocoding powered by 446M+ addresses worldwide.
+
+## Installation
+
+```bash
+pip install csv2geo
+```
+
+## Quick Start
+
+```python
+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
+
+```python
+from csv2geo import Client
+
+client = Client(
+    api_key="your_api_key",
+    base_url="https://api.csv2geo.com/v1",  # optional
+    timeout=30,  # optional, seconds
+    auto_retry=True,  # optional, retry on rate limit
+)
+```
+
+### Forward Geocoding
+
+```python
+# 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
+
+```python
+# 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
+
+```python
+# 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
+
+```python
+# 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)
+```
+
+### GeocodeResult Object
+
+```python
+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
+
+```python
+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:
+
+```python
+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
+
+```python
+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](https://csv2geo.com) to get your API key.
+
+## Documentation
+
+- [API Documentation](https://acenji.github.io/csv2geo-api/docs/)
+- [OpenAPI Specification](https://github.com/acenji/csv2geo-api/blob/main/openapi.yaml)
+
+## License
+
+MIT License - see [LICENSE](https://github.com/acenji/csv2geo-api/blob/main/LICENSE) for details.

csv2geo-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+csv2geo/__init__.py,sha256=R4rmKzyLdyvemq94lvnuv6BYBOpTnv6X9IcWz7mZsd4,715
+csv2geo/client.py,sha256=onNIAI61GOoEqQoyVAj-7dscifofDuvkyEWZOlGa5o8,10211
+csv2geo/exceptions.py,sha256=kNJTjEUAyyww90zyaBq28KR1O5CF_tId1zQsJhki4DQ,966
+csv2geo/models.py,sha256=8ETXkGv1QAb_zKyMwNaVOD5JaadUBmB0gCyzHoGLym0,3388
+csv2geo-1.0.0.dist-info/METADATA,sha256=8qSKeBVZgYYCtO-lk5GIO0EZmLg1wN7JZf1BMgcWe3U,6515
+csv2geo-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+csv2geo-1.0.0.dist-info/top_level.txt,sha256=JtWH-UwBAgITeusXhvWkqPfjbuzexKsaf4q5JxeJtkw,8
+csv2geo-1.0.0.dist-info/RECORD,,

csv2geo-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

csv2geo-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+csv2geo