feat: add housing support

- Add Housing model for ACS housing data

- Add housing to GeocodioFields

- Add unit and integration tests for housing

Author: funkatron

src/geocodio/client.py

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

src/geocodio/models.py

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

tests/e2e/test_api.py

@@ -397,4 +397,42 @@ def test_integration_with_families(client):
         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)
+            assert isinstance(fields.families.average_household_size, float)
+
+
+def test_integration_with_housing(client):
+    """Test real API call with housing field."""
+    # Test address
+    address = "1600 Pennsylvania Ave NW, Washington, DC"
+
+    # Request additional fields
+    response = client.geocode(
+        address,
+        fields=["acs-housing"]
+    )
+
+    # 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 housing data
+    if fields.housing:
+        if fields.housing.total_housing_units is not None:
+            assert isinstance(fields.housing.total_housing_units, int)
+        if fields.housing.occupied_housing_units is not None:
+            assert isinstance(fields.housing.occupied_housing_units, int)
+        if fields.housing.vacant_housing_units is not None:
+            assert isinstance(fields.housing.vacant_housing_units, int)
+        if fields.housing.owner_occupied_units is not None:
+            assert isinstance(fields.housing.owner_occupied_units, int)
+        if fields.housing.renter_occupied_units is not None:
+            assert isinstance(fields.housing.renter_occupied_units, int)
+        if fields.housing.median_home_value is not None:
+            assert isinstance(fields.housing.median_home_value, int)
+        if fields.housing.median_rent is not None:
+            assert isinstance(fields.housing.median_rent, int)

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, Families
+    GeocodioFields, GeocodingResult, GeocodingResponse, Location, StateLegislativeDistrict, SchoolDistrict, CensusData, Demographics, Economics, Families, Housing
 )
 
 
@@ -232,4 +232,30 @@ def test_families_extras():
     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"
+    assert families.get_extra("nonexistent", "default") == "default"
+
+
+def test_housing_extras():
+    # Test that extra fields are stored in extras
+    data = {
+        "total_housing_units": 1000,
+        "occupied_housing_units": 800,
+        "vacant_housing_units": 200,
+        "owner_occupied_units": 500,
+        "renter_occupied_units": 300,
+        "median_home_value": 350000,
+        "median_rent": 1500,
+        "extra_field": "extra value"
+    }
+
+    housing = Housing.from_api(data)
+
+    assert housing.total_housing_units == 1000
+    assert housing.occupied_housing_units == 800
+    assert housing.vacant_housing_units == 200
+    assert housing.owner_occupied_units == 500
+    assert housing.renter_occupied_units == 300
+    assert housing.median_home_value == 350000
+    assert housing.median_rent == 1500
+    assert housing.get_extra("extra_field") == "extra value"
+    assert housing.get_extra("nonexistent", "default") == "default"