feat: add economics support

- Add Economics model for ACS economics data

- Add economics to GeocodioFields

- Add unit and integration tests for economics

Author: funkatron

src/geocodio/client.py

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

src/geocodio/models.py

@@ -151,6 +151,19 @@ class Demographics(_HasExtras, ApiModelMixin):
     extras: Dict[str, Any] = field(default_factory=dict, repr=False)
 
 
+@dataclass(slots=True, frozen=True)
+class Economics(_HasExtras, 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 GeocodioFields:
     """
@@ -167,6 +180,7 @@ class GeocodioFields:
     census2023: Optional[CensusData] = None
     acs: Optional[ACSSurveyData] = None
     demographics: Optional[Demographics] = None
+    economics: Optional[Economics] = None
 
 
 # ──────────────────────────────────────────────────────────────────────────────

tests/e2e/test_api.py

@@ -325,4 +325,38 @@ def test_integration_with_demographics(client):
         if fields.demographics.asian_population is not None:
             assert isinstance(fields.demographics.asian_population, int)
         if fields.demographics.hispanic_population is not None:
-            assert isinstance(fields.demographics.hispanic_population, int)
+            assert isinstance(fields.demographics.hispanic_population, int)
+
+
+def test_integration_with_economics(client):
+    """Test real API call with economics field."""
+    # Test address
+    address = "1600 Pennsylvania Ave NW, Washington, DC"
+
+    # Request additional fields
+    response = client.geocode(
+        address,
+        fields=["acs-economics"]
+    )
+
+    # 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 economics data
+    if fields.economics:
+        if fields.economics.median_household_income is not None:
+            assert isinstance(fields.economics.median_household_income, int)
+        if fields.economics.mean_household_income is not None:
+            assert isinstance(fields.economics.mean_household_income, int)
+        if fields.economics.per_capita_income is not None:
+            assert isinstance(fields.economics.per_capita_income, int)
+        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)

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
+    GeocodioFields, GeocodingResult, GeocodingResponse, Location, StateLegislativeDistrict, SchoolDistrict, CensusData, Demographics, Economics
 )
 
 
@@ -184,4 +184,26 @@ def test_demographics_extras():
     assert demographics.asian_population == 100
     assert demographics.hispanic_population == 100
     assert demographics.get_extra("extra_field") == "extra value"
-    assert demographics.get_extra("nonexistent", "default") == "default"
+    assert demographics.get_extra("nonexistent", "default") == "default"
+
+
+def test_economics_extras():
+    # Test that extra fields are stored in extras
+    data = {
+        "median_household_income": 75000,
+        "mean_household_income": 85000,
+        "per_capita_income": 35000,
+        "poverty_rate": 10.5,
+        "unemployment_rate": 5.2,
+        "extra_field": "extra value"
+    }
+
+    economics = Economics.from_api(data)
+
+    assert economics.median_household_income == 75000
+    assert economics.mean_household_income == 85000
+    assert economics.per_capita_income == 35000
+    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"