geocodio-library-python 0.1.0__py3-none-any.whl

geocodio/__init__.py

@@ -0,0 +1,9 @@
+"""
+Geocodio Python Client
+A Python client for the Geocodio API.
+"""
+
+from ._version import __version__
+from .client import GeocodioClient
+
+__all__ = ["GeocodioClient", "__version__"]

geocodio/_version.py

@@ -0,0 +1,3 @@
+"""Version information for geocodio package."""
+
+__version__ = "0.1.0"

geocodio/client.py

@@ -0,0 +1,583 @@
+"""
+src/geocodio/client.py
+High‑level synchronous client for the Geocodio API.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import List, Union, Dict, Tuple, Optional
+
+import httpx
+
+from geocodio._version import __version__
+
+# Set up logger early to capture all logs
+logger = logging.getLogger("geocodio")
+
+# flake8: noqa: F401
+from geocodio.models import (
+    GeocodingResponse, GeocodingResult, AddressComponents,
+    Location, GeocodioFields, Timezone, CongressionalDistrict,
+    CensusData, ACSSurveyData, StateLegislativeDistrict, SchoolDistrict,
+    Demographics, Economics, Families, Housing, Social,
+    FederalRiding, ProvincialRiding, StatisticsCanadaData, ListResponse, PaginatedResponse
+)
+from geocodio.exceptions import InvalidRequestError, AuthenticationError, GeocodioServerError, BadRequestError
+
+
+class GeocodioClient:
+    BASE_PATH = "/v1.9"  # keep in sync with Geocodio's current version
+    DEFAULT_SINGLE_TIMEOUT = 5.0
+    DEFAULT_BATCH_TIMEOUT = 1800.0  # 30 minutes
+    LIST_API_TIMEOUT = 60.0
+    USER_AGENT = f"geocodio-library-python/{__version__}"
+
+    @staticmethod
+    def get_status_exception_mappings() -> Dict[
+        int, type[BadRequestError | InvalidRequestError | AuthenticationError | GeocodioServerError]
+    ]:
+        """
+        Returns a list of status code to exception mappings.
+        This is used to map HTTP status codes to specific exceptions.
+        """
+        return {
+            400: BadRequestError,
+            422: InvalidRequestError,
+            403: AuthenticationError,
+            500: GeocodioServerError,
+        }
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        hostname: str = "api.geocod.io",
+        single_timeout: Optional[float] = None,
+        batch_timeout: Optional[float] = None,
+        list_timeout: Optional[float] = None,
+    ):
+        self.api_key: str = api_key or os.getenv("GEOCODIO_API_KEY", "")
+        if not self.api_key:
+            raise AuthenticationError(
+                detail="No API key supplied and GEOCODIO_API_KEY is not set."
+            )
+        self.hostname = hostname.rstrip("/")
+        self.single_timeout = single_timeout or self.DEFAULT_SINGLE_TIMEOUT
+        self.batch_timeout = batch_timeout or self.DEFAULT_BATCH_TIMEOUT
+        self.list_timeout = list_timeout or self.LIST_API_TIMEOUT
+        self._http = httpx.Client(base_url=f"https://{self.hostname}")
+
+    # ──────────────────────────────────────────────────────────────────────────
+    # Public methods
+    # ──────────────────────────────────────────────────────────────────────────
+
+    def geocode(
+            self,
+            address: Union[
+                str, Dict[str, str], List[Union[str, Dict[str, str]]], Dict[str, Union[str, Dict[str, str]]]],
+            fields: Optional[List[str]] = None,
+            limit: Optional[int] = None,
+            country: Optional[str] = None,
+    ) -> GeocodingResponse:
+        params: Dict[str, Union[str, int]] = {}
+        if fields:
+            params["fields"] = ",".join(fields)
+        if limit:
+            params["limit"] = int(limit)
+        if country:
+            params["country"] = country
+
+        endpoint: str
+        data: Union[List, Dict] | None
+
+        # Handle different input types
+        if isinstance(address, dict) and not any(isinstance(v, dict) for v in address.values()):
+            # Single structured address
+            endpoint = f"{self.BASE_PATH}/geocode"
+            # Map our parameter names to API parameter names
+            param_map = {
+                "street": "street",
+                "street2": "street2",
+                "city": "city",
+                "county": "county",
+                "state": "state",
+                "postal_code": "postal_code",
+                "country": "country",
+            }
+            # Only include parameters that are present in the input
+            for key, value in address.items():
+                if key in param_map and value:
+                    params[param_map[key]] = value
+            data = None
+        elif isinstance(address, list):
+            # Batch addresses - send list directly
+            endpoint = f"{self.BASE_PATH}/geocode"
+            data = address
+        elif isinstance(address, dict) and any(isinstance(v, dict) for v in address.values()):
+            # Batch addresses with custom keys
+            endpoint = f"{self.BASE_PATH}/geocode"
+            data = {"addresses": list(address.values()), "keys": list(address.keys())}
+        else:
+            # Single address string
+            endpoint = f"{self.BASE_PATH}/geocode"
+            params["q"] = address
+            data = None
+
+        timeout = self.batch_timeout if data else self.single_timeout
+        response = self._request("POST" if data else "GET", endpoint, params, json=data, timeout=timeout)
+        return self._parse_geocoding_response(response.json())
+
+    def reverse(
+            self,
+            coordinate: Union[str, Tuple[float, float], List[Union[str, Tuple[float, float]]]],
+            fields: Optional[List[str]] = None,
+            limit: Optional[int] = None,
+    ) -> GeocodingResponse:
+        params: Dict[str, Union[str, int]] = {}
+        if fields:
+            params["fields"] = ",".join(fields)
+        if limit:
+            params["limit"] = int(limit)
+
+        endpoint: str
+        data: Union[List[str], None]
+
+        # Batch vs single coordinate
+        if isinstance(coordinate, list):
+            endpoint = f"{self.BASE_PATH}/reverse"
+            coords_as_strings = []
+            for coord in coordinate:
+                if isinstance(coord, tuple):
+                    coords_as_strings.append(f"{coord[0]},{coord[1]}")
+                else:
+                    coords_as_strings.append(coord)
+            data = coords_as_strings
+        else:
+            endpoint = f"{self.BASE_PATH}/reverse"
+            if isinstance(coordinate, tuple):
+                params["q"] = f"{coordinate[0]},{coordinate[1]}"
+            else:
+                params["q"] = coordinate  # "lat,lng"
+            data = None
+
+        timeout = self.batch_timeout if data else self.single_timeout
+        response = self._request("POST" if data else "GET", endpoint, params, json=data, timeout=timeout)
+        return self._parse_geocoding_response(response.json())
+
+    # ──────────────────────────────────────────────────────────────────────────
+    # Internal helpers
+    # ──────────────────────────────────────────────────────────────────────────
+
+    def _request(
+            self,
+            method: str,
+            endpoint: str,
+            params: Optional[dict] = None,
+            json: Optional[dict] = None,
+            files: Optional[dict] = None,
+            timeout: Optional[float] = None,
+    ) -> httpx.Response:
+        logger.debug(f"Making Request: {method} {endpoint}")
+        logger.debug(f"Params: {params}")
+        logger.debug(f"JSON body: {json}")
+        logger.debug(f"Files: {files}")
+
+        if timeout is None:
+            timeout = self.single_timeout
+        
+        # Set up authorization and user-agent headers
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": self.USER_AGENT
+        }
+        
+        logger.debug(f"Using timeout: {timeout}s")
+        resp = self._http.request(method, endpoint, params=params, json=json, files=files, headers=headers, timeout=timeout)
+
+        logger.debug(f"Response status code: {resp.status_code}")
+        logger.debug(f"Response headers: {resp.headers}")
+        logger.debug(f"Response body: {resp.content}")
+
+        resp = self._handle_error_response(resp)
+
+        return resp
+
+    def _handle_error_response(self, resp) -> httpx.Response:
+        if resp.status_code < 400:
+            logger.debug("No error in response, returning normally.")
+            return resp
+
+        exception_mappings = self.get_status_exception_mappings()
+        # dump the type and content of the exception mappings for debugging
+        logger.error(f"Error response: {resp.status_code} - {resp.text}")
+        if resp.status_code in exception_mappings:
+            exception_class = exception_mappings[resp.status_code]
+            raise exception_class(resp.text)
+        else:
+            raise GeocodioServerError(f"Unrecognized status code {resp.status_code}: {resp.text}")
+
+    def _parse_geocoding_response(self, response_json: dict) -> GeocodingResponse:
+        logger.debug(f"Raw response: {response_json}")
+
+        # Handle batch response format
+        if "results" in response_json and isinstance(response_json["results"], list) and response_json[
+            "results"] and "response" in response_json["results"][0]:
+            results = [
+                GeocodingResult(
+                    address_components=AddressComponents.from_api(res["response"]["results"][0]["address_components"]),
+                    formatted_address=res["response"]["results"][0]["formatted_address"],
+                    location=Location(**res["response"]["results"][0]["location"]),
+                    accuracy=res["response"]["results"][0].get("accuracy", 0.0),
+                    accuracy_type=res["response"]["results"][0].get("accuracy_type", ""),
+                    source=res["response"]["results"][0].get("source", ""),
+                    fields=self._parse_fields(res["response"]["results"][0].get("fields")),
+                )
+                for res in response_json["results"]
+            ]
+            return GeocodingResponse(input=response_json.get("input", {}), results=results)
+
+        # Handle single response format
+        results = [
+            GeocodingResult(
+                address_components=AddressComponents.from_api(res["address_components"]),
+                formatted_address=res["formatted_address"],
+                location=Location(**res["location"]),
+                accuracy=res.get("accuracy", 0.0),
+                accuracy_type=res.get("accuracy_type", ""),
+                source=res.get("source", ""),
+                fields=self._parse_fields(res.get("fields")),
+            )
+            for res in response_json.get("results", [])
+        ]
+        return GeocodingResponse(input=response_json.get("input", {}), results=results)
+
+    # ──────────────────────────────────────────────────────────────────────────
+    # List API methods
+    # ──────────────────────────────────────────────────────────────────────────
+
+    DIRECTION_FORWARD = "forward"
+    DIRECTION_REVERSE = "reverse"
+
+    def create_list(
+            self,
+            file: Optional[str] = None,
+            filename: Optional[str] = None,
+            direction: str = DIRECTION_FORWARD,
+            format_: Optional[str] = "{{A}}",
+            callback_url: Optional[str] = None,
+            fields: list[str] | None = None
+    ) -> ListResponse:
+        """
+        Create a new geocoding list.
+
+        Args:
+            file: The file content as a string. Required.
+            filename: The name of the file. Defaults to "file.csv".
+            direction: The direction of geocoding. Either "forward" or "reverse". Defaults to "forward".
+            format_: The format string for the output. Defaults to "{{A}}".
+            callback_url: Optional URL to call when processing is complete.
+            fields: Optional list of fields to include in the response. Valid fields include:
+                   - census2010, census2020, census2023
+                   - cd, cd113-cd119 (congressional districts)
+                   - stateleg, stateleg-next (state legislative districts)
+                   - school (school districts)
+                   - timezone
+                   - acs, acs-demographics, acs-economics, acs-families, acs-housing, acs-social
+                   - riding, provriding, provriding-next (Canadian data)
+                   - statcan (Statistics Canada data)
+                   - zip4 (ZIP+4 data)
+                   - ffiec (FFIEC data, beta)
+
+        Returns:
+            A ListResponse object containing the created list information.
+
+        Raises:
+            ValueError: If file is not provided.
+            InvalidRequestError: If the API request is invalid.
+            AuthenticationError: If the API key is invalid.
+            GeocodioServerError: If the server encounters an error.
+        """
+        params: Dict[str, Union[str, int]] = {}
+        endpoint = f"{self.BASE_PATH}/lists"
+
+        if not file:
+            raise ValueError("File data is required to create a list.")
+        filename = filename or "file.csv"
+        files = {
+            "file": (filename, file),
+        }
+        if direction:
+            params["direction"] = direction
+        if format_:
+            params["format"] = format_
+        if callback_url:
+            params["callback"] = callback_url
+        if fields:
+            # Join fields with commas as required by the API
+            params["fields"] = ",".join(fields)
+
+        response = self._request("POST", endpoint, params, files=files, timeout=self.list_timeout)
+        logger.debug(f"Response content: {response.text}")
+        return self._parse_list_response(response.json(), response=response)
+
+    def get_lists(self) -> PaginatedResponse:
+        """
+        Retrieve all lists.
+
+        Returns:
+            A ListResponse object containing all lists.
+        """
+        params: Dict[str, Union[str, int]] = {}
+        endpoint = f"{self.BASE_PATH}/lists"
+
+        response = self._request("GET", endpoint, params, timeout=self.list_timeout)
+        pagination_info = response.json()
+
+        logger.debug(f"Pagination info: {pagination_info}")
+
+        response_lists = []
+        for list_item in pagination_info.get("data", []):
+            logger.debug(f"List item: {list_item}")
+            response_lists.append(self._parse_list_response(list_item, response=response))
+
+        return PaginatedResponse(
+            data=response_lists,
+            current_page=pagination_info.get("current_page", 1),
+            from_=pagination_info.get("from", 0),
+            to=pagination_info.get("to", 0),
+            path=pagination_info.get("path", ""),
+            per_page=pagination_info.get("per_page", 10),
+            first_page_url=pagination_info.get("first_page_url"),
+            next_page_url=pagination_info.get("next_page_url"),
+            prev_page_url=pagination_info.get("prev_page_url")
+        )
+
+    def get_list(self, list_id: str) -> ListResponse:
+        """
+        Retrieve a list by ID.
+
+        Args:
+            list_id: The ID of the list to retrieve.
+
+        Returns:
+            A ListResponse object containing the retrieved list.
+        """
+        params: Dict[str, Union[str, int]] = {}
+        endpoint = f"{self.BASE_PATH}/lists/{list_id}"
+
+        response = self._request("GET", endpoint, params, timeout=self.list_timeout)
+        return self._parse_list_response(response.json(), response=response)
+
+    def delete_list(self, list_id: str) -> None:
+        """
+        Delete a list.
+
+        Args:
+            list_id: The ID of the list to delete.
+        """
+        params: Dict[str, Union[str, int]] = {}
+        endpoint = f"{self.BASE_PATH}/lists/{list_id}"
+
+        self._request("DELETE", endpoint, params, timeout=self.list_timeout)
+
+    @staticmethod
+    def _parse_list_response(response_json: dict, response: httpx.Response = None) -> ListResponse:
+        """
+        Parse a response from the List API.
+
+        Args:
+            response_json: The JSON response from the List API.
+
+        Returns:
+            A ListResponse object.
+        """
+        logger.debug(f"{response_json}")
+        return ListResponse(
+            id=response_json.get("id"),
+            file=response_json.get("file"),
+            status=response_json.get("status"),
+            download_url=response_json.get("download_url"),
+            expires_at=response_json.get("expires_at"),
+            http_response=response,
+        )
+
+    def _parse_fields(self, fields_data: dict | None) -> GeocodioFields | None:
+        if not fields_data:
+            return None
+
+        timezone = (
+            Timezone.from_api(fields_data["timezone"])
+            if "timezone" in fields_data else None
+        )
+        congressional_districts = None
+        if "cd" in fields_data:
+            congressional_districts = [
+                CongressionalDistrict.from_api(cd)
+                for cd in fields_data["cd"]
+            ]
+        elif "congressional_districts" in fields_data:
+            congressional_districts = [
+                CongressionalDistrict.from_api(cd)
+                for cd in fields_data["congressional_districts"]
+            ]
+
+        state_legislative_districts = None
+        if "stateleg" in fields_data:
+            state_legislative_districts = [
+                StateLegislativeDistrict.from_api(district)
+                for district in fields_data["stateleg"]
+            ]
+
+        state_legislative_districts_next = None
+        if "stateleg-next" in fields_data:
+            state_legislative_districts_next = [
+                StateLegislativeDistrict.from_api(district)
+                for district in fields_data["stateleg-next"]
+            ]
+
+        school_districts = None
+        if "school" in fields_data:
+            school_districts = [
+                SchoolDistrict.from_api(district)
+                for district in fields_data["school"]
+            ]
+
+        census2010 = (
+            CensusData.from_api(fields_data["census2010"])
+            if "census2010" in fields_data else None
+        )
+
+        census2020 = (
+            CensusData.from_api(fields_data["census2020"])
+            if "census2020" in fields_data else None
+        )
+
+        census2023 = (
+            CensusData.from_api(fields_data["census2023"])
+            if "census2023" in fields_data else None
+        )
+
+        acs = (
+            ACSSurveyData.from_api(fields_data["acs"])
+            if "acs" in fields_data else None
+        )
+
+        demographics = (
+            Demographics.from_api(fields_data["acs-demographics"])
+            if "acs-demographics" in fields_data else None
+        )
+
+        economics = (
+            Economics.from_api(fields_data["acs-economics"])
+            if "acs-economics" in fields_data else None
+        )
+
+        families = (
+            Families.from_api(fields_data["acs-families"])
+            if "acs-families" in fields_data else None
+        )
+
+        housing = (
+            Housing.from_api(fields_data["acs-housing"])
+            if "acs-housing" in fields_data else None
+        )
+
+        social = (
+            Social.from_api(fields_data["acs-social"])
+            if "acs-social" in fields_data else None
+        )
+
+        # Canadian fields
+        riding = (
+            FederalRiding.from_api(fields_data["riding"])
+            if "riding" in fields_data else None
+        )
+
+        provriding = (
+            ProvincialRiding.from_api(fields_data["provriding"])
+            if "provriding" in fields_data else None
+        )
+
+        provriding_next = (
+            ProvincialRiding.from_api(fields_data["provriding-next"])
+            if "provriding-next" in fields_data else None
+        )
+
+        statcan = (
+            StatisticsCanadaData.from_api(fields_data["statcan"])
+            if "statcan" in fields_data else None
+        )
+
+        return GeocodioFields(
+            timezone=timezone,
+            congressional_districts=congressional_districts,
+            state_legislative_districts=state_legislative_districts,
+            state_legislative_districts_next=state_legislative_districts_next,
+            school_districts=school_districts,
+            census2010=census2010,
+            census2020=census2020,
+            census2023=census2023,
+            acs=acs,
+            demographics=demographics,
+            economics=economics,
+            families=families,
+            housing=housing,
+            social=social,
+            riding=riding,
+            provriding=provriding,
+            provriding_next=provriding_next,
+            statcan=statcan,
+        )
+
+    # @TODO add a "keep_trying" parameter to download() to keep trying until the list is processed.
+    def download(self, list_id: str, filename: Optional[str] = None) -> str | bytes:
+        """
+        This will generate/retrieve the fully geocoded list as a CSV file, and either return the content as bytes
+        or save the file to disk with the provided filename.
+
+        Args:
+            list_id: The ID of the list to download.
+            filename: filename to assign to the file (optional). If provided, the content will be saved to this file.
+
+        Returns:
+            The content of the file as a Bytes object, or the full file path string if filename is provided.
+        Raises:
+            GeocodioServerError if the list is still processing or another error occurs.
+        """
+        params = {}
+        endpoint = f"{self.BASE_PATH}/lists/{list_id}/download"
+
+        response: httpx.Response = self._request("GET", endpoint, params, timeout=self.list_timeout)
+        if response.headers.get("content-type", "").startswith("application/json"):
+            try:
+                error = response.json()
+                logger.error(f"Error downloading list {list_id}: {error}")
+                raise GeocodioServerError(error.get("message", "Failed to download list."))
+            except Exception as e:
+                logger.error(f"Failed to parse error message from response: {response.text}", exc_info=True)
+                raise GeocodioServerError("Failed to download list and could not parse error message.") from e
+        else:
+            if filename:
+                # If a filename is provided, save the response content to a file of that name=
+                # get the absolute path of the file
+                if not os.path.isabs(filename):
+                    filename = os.path.abspath(filename)
+                # Ensure the directory exists
+                os.makedirs(os.path.dirname(filename), exist_ok=True)
+                logger.debug(f"Saving list {list_id} to {filename}")
+
+                # do not check if the file exists, just overwrite it
+                if os.path.exists(filename):
+                    logger.debug(f"File {filename} already exists; it will be overwritten.")
+
+                try:
+                    with open(filename, "wb") as f:
+                        f.write(response.content)
+                    logger.info(f"List {list_id} downloaded and saved to {filename}")
+                    return filename  # Return the full path of the saved file
+                except IOError as e:
+                    logger.error(f"Failed to save list {list_id} to {filename}: {e}", exc_info=True)
+                    raise GeocodioServerError(f"Failed to save list: {e}")
+            else:  # return the bytes content directly
+                return response.content

geocodio/exceptions.py

@@ -0,0 +1,72 @@
+"""
+src/geocodio/exceptions.py
+Structured exception hierarchy for the Geocodio Python client.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, List, Union
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Data container
+# ──────────────────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True, slots=True)
+class GeocodioErrorDetail:
+    """
+    A typed record returned by Geocodio on errors.
+    """
+    message: str
+    code: Optional[int] = None  # e.g. HTTP status or internal
+    errors: Optional[List[str]] = None  # field‑specific validation messages
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Base + specific exceptions
+# ──────────────────────────────────────────────────────────────────────────────
+
+class GeocodioError(Exception):
+    """Root of the library’s exception hierarchy."""
+
+    def __init__(self, detail: Union[str, GeocodioErrorDetail]):
+        if isinstance(detail, str):
+            self.detail = GeocodioErrorDetail(message=detail)
+        else:
+            self.detail = detail
+        super().__init__(self.detail.message)
+
+    def __str__(self) -> str:  # prettier default printing
+        return self.detail.message
+
+
+class BadRequestError(GeocodioError):
+    """400 Bad Request – invalid input / validation failure."""
+
+
+class InvalidRequestError(GeocodioError):
+    """422 Unprocessable Entity – invalid input / validation failure."""
+
+
+class AuthenticationError(GeocodioError):
+    """401/403 – missing or incorrect API key, or insufficient permissions."""
+
+
+class GeocodioServerError(GeocodioError):
+    """5xx – Geocodio internal error."""
+
+
+class DefaultHTTPError(GeocodioError):
+    """Other HTTP error – 4xx or 5xx, but not one of the above."""
+
+
+__all__ = [
+    "GeocodioErrorDetail",
+    "GeocodioError",
+    "BadRequestError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "GeocodioServerError",
+    "DefaultHTTPError",
+]

geocodio/models.py

@@ -0,0 +1,400 @@
+"""
+src/geocodio/models.py
+Dataclass representations of Geocodio API responses and related objects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional, Dict, TypeVar, Type
+
+import httpx
+
+T = TypeVar("T", bound="ExtrasMixin")
+
+
+class ExtrasMixin:
+    """Mixin to provide additional functionality for API response models."""
+
+    extras: Dict[str, Any]
+
+    def get_extra(self, key: str, default=None):
+        return self.extras.get(key, default)
+
+    def __getattr__(self, item):
+        try:
+            return self.extras[item]
+        except KeyError as exc:
+            raise AttributeError(item) from exc
+
+
+class ApiModelMixin(ExtrasMixin):
+    """Mixin to provide additional functionality for API response models."""
+
+    @classmethod
+    def from_api(cls: Type[T], data: Dict[str, Any]) -> T:
+        """Create an instance from API response data.
+
+        Known fields are extracted and passed to the constructor.
+        Unknown fields are stored in the extras dictionary.
+        """
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        core = {k: v for k, v in data.items() if k in known}
+        extra = {k: v for k, v in data.items() if k not in known}
+        return cls(**core, extras=extra)
+
+
+@dataclass(slots=True, frozen=True)
+class Location:
+    lat: float
+    lng: float
+
+
+@dataclass(frozen=True)
+class AddressComponents(ApiModelMixin):
+    # core / always-present
+    number: Optional[str] = None
+    predirectional: Optional[str] = None  # e.g. "N"
+    street: Optional[str] = None
+    suffix: Optional[str] = None  # e.g. "St"
+    postdirectional: Optional[str] = None
+    formatted_street: Optional[str] = None  # full street line
+
+    city: Optional[str] = None
+    county: Optional[str] = None
+    state: Optional[str] = None
+    zip: Optional[str] = None  # Geocodio returns "zip"
+    postal_code: Optional[str] = None  # alias for completeness
+    country: Optional[str] = None
+
+    # catch‑all for anything Geocodio adds later
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(frozen=True)
+class Timezone(ApiModelMixin):
+    name: str
+    utc_offset: int
+    observes_dst: Optional[bool] = None  # new key documented by Geocodio
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class CongressionalDistrict(ApiModelMixin):
+    name: str
+    district_number: int
+    congress_number: str
+    ocd_id: Optional[str] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class StateLegislativeDistrict(ApiModelMixin):
+    """
+    State legislative district information.
+    """
+
+    name: str
+    district_number: int
+    chamber: str  # 'house' or 'senate'
+    ocd_id: Optional[str] = None
+    proportion: Optional[float] = None  # Proportion of overlap with the address
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class CensusData(ApiModelMixin):
+    """
+    Census data for a location.
+    """
+
+    block: Optional[str] = None
+    blockgroup: Optional[str] = None
+    tract: Optional[str] = None
+    county_fips: Optional[str] = None
+    state_fips: Optional[str] = None
+    msa_code: Optional[str] = None  # Metropolitan Statistical Area
+    csa_code: Optional[str] = None  # Combined Statistical Area
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class ACSSurveyData(ApiModelMixin):
+    """
+    American Community Survey data for a location.
+    """
+
+    population: Optional[int] = None
+    households: Optional[int] = None
+    median_income: Optional[int] = None
+    median_age: Optional[float] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class SchoolDistrict(ApiModelMixin):
+    """
+    School district information.
+    """
+
+    name: str
+    district_number: Optional[str] = None
+    lea_id: Optional[str] = None  # Local Education Agency ID
+    nces_id: Optional[str] = None  # National Center for Education Statistics ID
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class Demographics(ApiModelMixin):
+    """
+    American Community Survey demographics data.
+    """
+
+    total_population: Optional[int] = None
+    male_population: Optional[int] = None
+    female_population: Optional[int] = None
+    median_age: Optional[float] = None
+    white_population: Optional[int] = None
+    black_population: Optional[int] = None
+    asian_population: Optional[int] = None
+    hispanic_population: Optional[int] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class Economics(ApiModelMixin):
+    """
+    American Community Survey economics data.
+    """
+
+    median_household_income: Optional[int] = None
+    mean_household_income: Optional[int] = None
+    per_capita_income: Optional[int] = None
+    poverty_rate: Optional[float] = None
+    unemployment_rate: Optional[float] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class Families(ApiModelMixin):
+    """
+    American Community Survey families data.
+    """
+
+    total_households: Optional[int] = None
+    family_households: Optional[int] = None
+    nonfamily_households: Optional[int] = None
+    married_couple_households: Optional[int] = None
+    single_male_households: Optional[int] = None
+    single_female_households: Optional[int] = None
+    average_household_size: Optional[float] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class Housing(ApiModelMixin):
+    """
+    American Community Survey housing data.
+    """
+
+    total_housing_units: Optional[int] = None
+    occupied_housing_units: Optional[int] = None
+    vacant_housing_units: Optional[int] = None
+    owner_occupied_units: Optional[int] = None
+    renter_occupied_units: Optional[int] = None
+    median_home_value: Optional[int] = None
+    median_rent: Optional[int] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class Social(ApiModelMixin):
+    """
+    American Community Survey social data.
+    """
+
+    high_school_graduate_or_higher: Optional[int] = None
+    bachelors_degree_or_higher: Optional[int] = None
+    graduate_degree_or_higher: Optional[int] = None
+    veterans: Optional[int] = None
+    veterans_percentage: Optional[float] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class ZIP4Data(ApiModelMixin):
+    """USPS ZIP+4 code and delivery information."""
+
+    zip4: str
+    delivery_point: str
+    carrier_route: str
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class FederalRiding(ApiModelMixin):
+    """Canadian federal electoral district information."""
+
+    code: str
+    name_english: str
+    name_french: str
+    ocd_id: str
+    year: int
+    source: str
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class ProvincialRiding(ApiModelMixin):
+    """Canadian provincial electoral district information."""
+
+    name_english: str
+    name_french: str
+    ocd_id: str
+    is_upcoming_district: bool
+    source: str
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class StatisticsCanadaData(ApiModelMixin):
+    """Canadian statistical boundaries from Statistics Canada."""
+
+    division: Dict[str, Any]
+    consolidated_subdivision: Dict[str, Any]
+    subdivision: Dict[str, Any]
+    economic_region: str
+    statistical_area: Dict[str, Any]
+    cma_ca: Dict[str, Any]
+    tract: str
+    population_centre: Dict[str, Any]
+    dissemination_area: Dict[str, Any]
+    dissemination_block: Dict[str, Any]
+    census_year: int
+    designated_place: Optional[Dict[str, Any]] = None
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class FFIECData(ApiModelMixin):
+    """FFIEC CRA/HMDA Data (Beta)."""
+
+    # Add FFIEC specific fields as they become available
+    extras: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass(slots=True, frozen=True)
+class GeocodioFields:
+    """
+    Container for optional 'fields' returned by the Geocodio API.
+    Add new attributes as additional data‑append endpoints become useful.
+    """
+
+    timezone: Optional[Timezone] = None
+    congressional_districts: Optional[List[CongressionalDistrict]] = None
+    state_legislative_districts: Optional[List[StateLegislativeDistrict]] = None
+    state_legislative_districts_next: Optional[List[StateLegislativeDistrict]] = None
+    school_districts: Optional[List[SchoolDistrict]] = None
+
+    # Census data for all available years
+    census2000: Optional[CensusData] = None
+    census2010: Optional[CensusData] = None
+    census2011: Optional[CensusData] = None
+    census2012: Optional[CensusData] = None
+    census2013: Optional[CensusData] = None
+    census2014: Optional[CensusData] = None
+    census2015: Optional[CensusData] = None
+    census2016: Optional[CensusData] = None
+    census2017: Optional[CensusData] = None
+    census2018: Optional[CensusData] = None
+    census2019: Optional[CensusData] = None
+    census2020: Optional[CensusData] = None
+    census2021: Optional[CensusData] = None
+    census2022: Optional[CensusData] = None
+    census2023: Optional[CensusData] = None
+    census2024: Optional[CensusData] = None
+
+    # ACS data
+    acs: Optional[ACSSurveyData] = None
+    demographics: Optional[Demographics] = None
+    economics: Optional[Economics] = None
+    families: Optional[Families] = None
+    housing: Optional[Housing] = None
+    social: Optional[Social] = None
+
+    # New fields
+    zip4: Optional[ZIP4Data] = None
+    ffiec: Optional[FFIECData] = None
+
+    # Canadian fields
+    riding: Optional[FederalRiding] = None
+    provriding: Optional[ProvincialRiding] = None
+    provriding_next: Optional[ProvincialRiding] = None
+    statcan: Optional[StatisticsCanadaData] = None
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Main result objects
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(slots=True, frozen=True)
+class GeocodingResult:
+    address_components: AddressComponents
+    formatted_address: str
+    location: Location
+    accuracy: float
+    accuracy_type: str
+    source: str
+    fields: Optional[GeocodioFields] = None
+
+
+@dataclass(slots=True, frozen=True)
+class GeocodingResponse:
+    """
+    Top‑level structure returned by client.geocode() / client.reverse().
+    """
+
+    input: Dict[str, Optional[str]]
+    results: List[GeocodingResult] = field(default_factory=list)
+
+
+@dataclass(slots=True, frozen=True)
+class ListProcessingState:
+    """
+    Constants for list processing states returned by the Geocodio API.
+    """
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    PROCESSING = "PROCESSING"
+
+
+@dataclass(slots=True, frozen=True)
+class ListResponse:
+    """
+    status, download_url, expires_at are not always present.
+    """
+
+    id: str
+    file: Dict[str, Any]
+    status: Optional[Dict[str, Any]] = None
+    download_url: Optional[str] = None
+    expires_at: Optional[str] = None
+    http_response: Optional[httpx.Response] = None
+
+
+@dataclass(slots=True, frozen=True)
+class PaginatedResponse():
+    """
+    Base class for paginated responses.
+    """
+
+    current_page: int
+    data: List[ListResponse]
+    from_: int
+    to: int
+    path: str
+    per_page: int
+    first_page_url: str
+    next_page_url: Optional[str] = None
+    prev_page_url: Optional[str] = None

geocodio_library_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: geocodio-library-python
+Version: 0.1.0
+Summary: A Python client for the Geocodio API
+Project-URL: Homepage, https://www.geocod.io
+Project-URL: Documentation, https://www.geocod.io/docs/?python
+Project-URL: Repository, https://github.com/geocodio/geocodio-library-python
+Project-URL: Issues, https://github.com/geocodio/geocodio-library-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# geocodio
+
+The official Python client for the Geocodio API.
+
+Features
+--------
+
+- Forward geocoding of single addresses or in batches (up to 10,000 lookups).
+- Reverse geocoding of coordinates (single or batch).
+- Append additional data fields (e.g. congressional districts, timezone, census data).
+- Automatic parsing of address components.
+- Simple exception handling for authentication, data, and server errors.
+
+Installation
+------------
+
+Install via pip:
+
+    pip install geocodio-library-python
+
+Development Installation
+-----------------------
+
+1. Clone the repository:
+    ```bash
+    git clone https://github.com/geocodio/geocodio-library-python.git
+    cd geocodio-library-python
+    ```
+
+2. Create and activate a virtual environment:
+    ```bash
+    python -m venv venv
+    source venv/bin/activate  # On Windows: venv\Scripts\activate
+    ```
+
+3. Install development dependencies:
+    ```bash
+    pip install -e .
+    pip install -r requirements-dev.txt
+    ```
+
+Usage
+-----
+
+### Geocoding
+
+```python
+from geocodio import GeocodioClient
+
+# Initialize the client with your API key
+client = GeocodioClient("YOUR_API_KEY")
+
+# Single forward geocode
+response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+print(response.results[0].formatted_address)
+
+# Batch forward geocode
+addresses = [
+    "1600 Pennsylvania Ave, Washington, DC",
+    "1 Infinite Loop, Cupertino, CA"
+]
+batch_response = client.geocode(addresses)
+for result in batch_response.results:
+    print(result.formatted_address)
+
+# Single reverse geocode
+rev = client.reverse("38.9002898,-76.9990361")
+print(rev.results[0].formatted_address)
+
+# Append additional fields
+data = client.geocode(
+    "1600 Pennsylvania Ave, Washington, DC",
+    fields=["cd", "timezone"]
+)
+print(data.results[0].fields.timezone.name if data.results[0].fields.timezone else "No timezone data")
+```
+
+### List API
+
+The List API allows you to manage lists of addresses or coordinates for batch processing.
+
+```python
+from geocodio import GeocodioClient
+
+# Initialize the client with your API key
+client = GeocodioClient("YOUR_API_KEY")
+
+# Get all lists
+lists = client.get_lists()
+print(f"Found {len(lists.data)} lists")
+
+# Create a new list from a file
+with open("addresses.csv", "rb") as f:
+    new_list = client.create_list(
+        file=f,
+        filename="addresses.csv",
+        direction="forward"
+    )
+print(f"Created list: {new_list.id}")
+
+# Get a specific list
+list_details = client.get_list(new_list.id)
+print(f"List status: {list_details.status}")
+
+# Download a completed list
+if list_details.status and list_details.status.get("state") == "COMPLETED":
+    file_content = client.download(new_list.id, "downloaded_results.csv")
+    print("List downloaded successfully")
+
+# Delete a list
+client.delete_list(new_list.id)
+```
+
+Error Handling
+--------------
+
+```python
+from geocodio import GeocodioClient
+from geocodio.exceptions import AuthenticationError, InvalidRequestError
+
+try:
+    client = GeocodioClient("INVALID_API_KEY")
+    response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+
+try:
+    client = GeocodioClient("YOUR_API_KEY")
+    response = client.geocode("")  # Empty address
+except InvalidRequestError as e:
+    print(f"Invalid request: {e}")
+```
+
+Geocodio Enterprise
+-------------------
+
+To use this library with Geocodio Enterprise, pass `api.enterprise.geocod.io` as the `hostname` parameter when initializing the client:
+
+```python
+from geocodio import GeocodioClient
+
+# Initialize client for Geocodio Enterprise
+client = GeocodioClient(
+    "YOUR_API_KEY",
+    hostname="api.enterprise.geocod.io"
+)
+
+# All methods work the same as with the standard API
+response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+print(response.results[0].formatted_address)
+```
+
+Documentation
+-------------
+
+Full documentation is available at <https://www.geocod.io/docs/?python>.
+
+Contributing
+------------
+
+Contributions are welcome! Please open issues and pull requests on GitHub.
+
+Issues: <https://github.com/geocodio/geocodio-library-python/issues>
+
+License
+-------
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+CI & Publishing
+---------------
+
+- CI runs unit tests and linting on every push. E2E tests run if `GEOCODIO_API_KEY` is set as a secret.
+- PyPI publishing workflow supports both TestPyPI and PyPI. See `.github/workflows/publish.yml`.
+- Use `test_pypi_release.py` for local packaging and dry-run upload.
+
+### Testing GitHub Actions Workflows
+
+The project includes tests for GitHub Actions workflows using `act` for local development:
+
+```bash
+# Test all workflows (requires act and Docker)
+pytest tests/test_workflows.py
+
+# Test specific workflow
+pytest tests/test_workflows.py::test_ci_workflow
+pytest tests/test_workflows.py::test_publish_workflow
+```
+
+**Prerequisites:**
+- Install [act](https://github.com/nektos/act) for local GitHub Actions testing
+- Docker must be running
+- For publish workflow tests: Set `TEST_PYPI_API_TOKEN` environment variable
+
+**Note:** Workflow tests are automatically skipped in CI environments.

geocodio_library_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+geocodio/__init__.py,sha256=nPaebXk6Lw4juMV4MwqqprIpEykavwuUUO5HjTnp_qQ,184
+geocodio/_version.py,sha256=jUN0Ah8FsULBO6V6etYJKXJO88-gbkFCisxrzRi2U6k,70
+geocodio/client.py,sha256=hxDktdFP2DYqEIrrsYBlb1ZYrPyWPrfovZ1clKUigt0,23870
+geocodio/exceptions.py,sha256=2GCEE92z1v7PsRNy_5mpTA_ORb-XD4L05n3MFpbxSNU,2677
+geocodio/models.py,sha256=wkuK0geGoGJ_hej3-3D8p09crMkZjrepw5opPI0QWXo,12270
+geocodio_library_python-0.1.0.dist-info/METADATA,sha256=LbUynhi2n2Hw_rqBz8I3ovaP0MTCyZBNQruKOIK4uro,6710
+geocodio_library_python-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+geocodio_library_python-0.1.0.dist-info/licenses/LICENSE,sha256=cXy43FWeSEvbwi2shdVczetTRHL9ySoSv4wU6sq9b9I,1092
+geocodio_library_python-0.1.0.dist-info/RECORD,,

geocodio_library_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

geocodio_library_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Dotsquare LLC <hello@geocod.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.