feat: improve Canadian field support - Split CanadianRiding into FederalRiding and ProvincialRiding models, add complete StatisticsCanadaData model, update tests, fix dataclass field ordering

Author: funkatron

src/geocodio/client.py

@@ -14,7 +14,8 @@
     GeocodingResponse, GeocodingResult, AddressComponents,
     Location, GeocodioFields, Timezone, CongressionalDistrict,
     CensusData, ACSSurveyData, StateLegislativeDistrict, SchoolDistrict,
-    Demographics, Economics, Families, Housing
+    Demographics, Economics, Families, Housing, Social,
+    FederalRiding, ProvincialRiding, StatisticsCanadaData
 )
 from .exceptions import InvalidRequestError, AuthenticationError, GeocodioServerError
 
@@ -40,12 +41,18 @@ def geocode(
         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,
+        format: Optional[str] = None,
     ) -> GeocodingResponse:
         params: Dict[str, Union[str, int]] = {"api_key": self.api_key}
         if fields:
             params["fields"] = ",".join(fields)
         if limit:
             params["limit"] = int(limit)
+        if country:
+            params["country"] = country
+        if format:
+            params["format"] = format
 
         endpoint: str
         data: Union[List, Dict] | None
@@ -54,7 +61,20 @@ def geocode(
         if isinstance(address, dict) and not any(isinstance(v, dict) for v in address.values()):
             # Single structured address
             endpoint = f"{self.BASE_PATH}/geocode"
-            params.update(address)
+            # 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
@@ -244,6 +264,32 @@ def _parse_fields(self, fields_data: dict | None) -> GeocodioFields | None:
             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,
@@ -258,4 +304,9 @@ def _parse_fields(self, fields_data: dict | None) -> GeocodioFields | None:
             economics=economics,
             families=families,
             housing=housing,
+            social=social,
+            riding=riding,
+            provriding=provriding,
+            provriding_next=provriding_next,
+            statcan=statcan,
         )

src/geocodio/models.py

@@ -194,6 +194,76 @@ class Housing(_HasExtras, ApiModelMixin):
     extras: Dict[str, Any] = field(default_factory=dict, repr=False)
 
 
+@dataclass(slots=True, frozen=True)
+class Social(_HasExtras, 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(_HasExtras, 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(_HasExtras, 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(_HasExtras, 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(_HasExtras, 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(_HasExtras, 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:
     """
@@ -205,14 +275,42 @@ class GeocodioFields:
     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
 
 
 # ──────────────────────────────────────────────────────────────────────────────