feat: add school districts support

- Add SchoolDistrict model

- Add school_districts to GeocodioFields

- Add unit and integration tests for school districts

Author: funkatron

src/geocodio/client.py

@@ -13,7 +13,7 @@
 from .models import (
     GeocodingResponse, GeocodingResult, AddressComponents,
     Location, GeocodioFields, Timezone, CongressionalDistrict,
-    CensusData, ACSSurveyData
+    CensusData, ACSSurveyData, StateLegislativeDistrict, SchoolDistrict
 )
 from .exceptions import InvalidRequestError, AuthenticationError, GeocodioServerError
 
@@ -182,6 +182,27 @@ def _parse_fields(self, fields_data: dict | None) -> GeocodioFields | None:
                 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
@@ -200,6 +221,9 @@ def _parse_fields(self, fields_data: dict | None) -> GeocodioFields | 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,
             acs=acs,

src/geocodio/models.py

@@ -121,6 +121,18 @@ class ACSSurveyData(_HasExtras, ApiModelMixin):
     extras: Dict[str, Any] = field(default_factory=dict, repr=False)
 
 
+@dataclass(slots=True, frozen=True)
+class SchoolDistrict(_HasExtras, 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 GeocodioFields:
     """
@@ -131,6 +143,7 @@ class GeocodioFields:
     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
     census2010: Optional[CensusData] = None
     census2020: Optional[CensusData] = None
     acs: Optional[ACSSurveyData] = None

tests/e2e/test_api.py

@@ -221,4 +221,36 @@ def test_integration_with_state_legislative_districts(client):
         if district.ocd_id:
             assert isinstance(district.ocd_id, str)
         if district.proportion:
-            assert isinstance(district.proportion, float)
+            assert isinstance(district.proportion, float)
+
+
+def test_integration_with_school_districts(client):
+    """Test real API call with school district fields."""
+    # Test address
+    address = "1600 Pennsylvania Ave NW, Washington, DC"
+
+    # Request additional fields
+    response = client.geocode(
+        address,
+        fields=["school"]
+    )
+
+    # 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 school districts
+    if fields.school_districts:
+        district = fields.school_districts[0]
+        assert district.name is not None
+        if district.district_number:
+            assert isinstance(district.district_number, str)
+        if district.lea_id:
+            assert isinstance(district.lea_id, str)
+        if district.nces_id:
+            assert isinstance(district.nces_id, str)

tests/test_models.py

@@ -1,7 +1,7 @@
 import pytest
 from geocodio.models import (
     AddressComponents, Timezone, CongressionalDistrict,
-    GeocodioFields, GeocodingResult, GeocodingResponse, Location, StateLegislativeDistrict
+    GeocodioFields, GeocodingResult, GeocodingResponse, Location, StateLegislativeDistrict, SchoolDistrict
 )
 
 
@@ -110,4 +110,24 @@ def test_state_legislative_district_extras():
     assert district.ocd_id == "ocd-division/country:us/state:va/sldl:8"
     assert district.proportion == 1.0
     assert district.get_extra("extra_field") == "extra value"
+    assert district.get_extra("nonexistent", "default") == "default"
+
+
+def test_school_district_extras():
+    # Test that extra fields are stored in extras
+    data = {
+        "name": "Arlington Public Schools",
+        "district_number": "001",
+        "lea_id": "5100000",
+        "nces_id": "5100000",
+        "extra_field": "extra value"
+    }
+
+    district = SchoolDistrict.from_api(data)
+
+    assert district.name == "Arlington Public Schools"
+    assert district.district_number == "001"
+    assert district.lea_id == "5100000"
+    assert district.nces_id == "5100000"
+    assert district.get_extra("extra_field") == "extra value"
     assert district.get_extra("nonexistent", "default") == "default"