feat: add families support

- Add Families model for ACS families data

- Add families to GeocodioFields

- Add unit and integration tests for families

Author: funkatron

src/geocodio/client.py

@@ -14,7 +14,7 @@
     GeocodingResponse, GeocodingResult, AddressComponents,
     Location, GeocodioFields, Timezone, CongressionalDistrict,
     CensusData, ACSSurveyData, StateLegislativeDistrict, SchoolDistrict,
-    Demographics, Economics
+    Demographics, Economics, Families
 )
 from .exceptions import InvalidRequestError, AuthenticationError, GeocodioServerError
 
@@ -234,6 +234,11 @@ def _parse_fields(self, fields_data: dict | None) -> GeocodioFields | None:
             if "acs-economics" in fields_data else None
         )
 
+        families = (
+            Families.from_api(fields_data["acs-families"])
+            if "acs-families" in fields_data else None
+        )
+
         return GeocodioFields(
             timezone=timezone,
             congressional_districts=congressional_districts,
@@ -246,4 +251,5 @@ def _parse_fields(self, fields_data: dict | None) -> GeocodioFields | None:
             acs=acs,
             demographics=demographics,
             economics=economics,
+            families=families,
         )

src/geocodio/models.py

@@ -164,6 +164,21 @@ class Economics(_HasExtras, ApiModelMixin):
     extras: Dict[str, Any] = field(default_factory=dict, repr=False)
 
 
+@dataclass(slots=True, frozen=True)
+class Families(_HasExtras, 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 GeocodioFields:
     """
@@ -181,6 +196,7 @@ class GeocodioFields:
     acs: Optional[ACSSurveyData] = None
     demographics: Optional[Demographics] = None
     economics: Optional[Economics] = None
+    families: Optional[Families] = None
 
 
 # ──────────────────────────────────────────────────────────────────────────────

tests/e2e/test_api.py

@@ -359,4 +359,42 @@ def test_integration_with_economics(client):
         if fields.economics.poverty_rate is not None:
             assert isinstance(fields.economics.poverty_rate, float)
         if fields.economics.unemployment_rate is not None:
-            assert isinstance(fields.economics.unemployment_rate, float)
+            assert isinstance(fields.economics.unemployment_rate, float)
+
+
+def test_integration_with_families(client):
+    """Test real API call with families field."""
+    # Test address
+    address = "1600 Pennsylvania Ave NW, Washington, DC"
+
+    # Request additional fields
+    response = client.geocode(
+        address,
+        fields=["acs-families"]
+    )
+
+    # Verify response structure
+    assert response is not None
+    assert len(response.results) > 0
+    result = response.results[0]
+
+    # Verify fields data
+    fields = result.fields
+    assert fields is not None
+
+    # Check families data
+    if fields.families:
+        if fields.families.total_households is not None:
+            assert isinstance(fields.families.total_households, int)
+        if fields.families.family_households is not None:
+            assert isinstance(fields.families.family_households, int)
+        if fields.families.nonfamily_households is not None:
+            assert isinstance(fields.families.nonfamily_households, int)
+        if fields.families.married_couple_households is not None:
+            assert isinstance(fields.families.married_couple_households, int)
+        if fields.families.single_male_households is not None:
+            assert isinstance(fields.families.single_male_households, int)
+        if fields.families.single_female_households is not None:
+            assert isinstance(fields.families.single_female_households, int)
+        if fields.families.average_household_size is not None:
+            assert isinstance(fields.families.average_household_size, float)

tests/test_models.py

@@ -1,7 +1,7 @@
 import pytest
 from geocodio.models import (
     AddressComponents, Timezone, CongressionalDistrict,
-    GeocodioFields, GeocodingResult, GeocodingResponse, Location, StateLegislativeDistrict, SchoolDistrict, CensusData, Demographics, Economics
+    GeocodioFields, GeocodingResult, GeocodingResponse, Location, StateLegislativeDistrict, SchoolDistrict, CensusData, Demographics, Economics, Families
 )
 
 
@@ -206,4 +206,30 @@ def test_economics_extras():
     assert economics.poverty_rate == 10.5
     assert economics.unemployment_rate == 5.2
     assert economics.get_extra("extra_field") == "extra value"
-    assert economics.get_extra("nonexistent", "default") == "default"
+    assert economics.get_extra("nonexistent", "default") == "default"
+
+
+def test_families_extras():
+    # Test that extra fields are stored in extras
+    data = {
+        "total_households": 1000,
+        "family_households": 600,
+        "nonfamily_households": 400,
+        "married_couple_households": 400,
+        "single_male_households": 100,
+        "single_female_households": 100,
+        "average_household_size": 2.5,
+        "extra_field": "extra value"
+    }
+
+    families = Families.from_api(data)
+
+    assert families.total_households == 1000
+    assert families.family_households == 600
+    assert families.nonfamily_households == 400
+    assert families.married_couple_households == 400
+    assert families.single_male_households == 100
+    assert families.single_female_households == 100
+    assert families.average_household_size == 2.5
+    assert families.get_extra("extra_field") == "extra value"
+    assert families.get_extra("nonexistent", "default") == "default"