Merge pull request #85 from ParclLabs/fix-geo-search

update location param to geographic_coordinates for prop search v2 endpoint

Author: bhagyasharma

CHANGELOG.md

@@ -1,3 +1,6 @@
+### v1.14.1
+- Update `property_v2.search` endpoint params.
+
 ### v1.13.0
 - Add support for `property_v2.search` endpoint.
 

README.md

@@ -485,11 +485,13 @@ addresses = client.property_address.search.retrieve(
 Gets a list of unique properties and their associated metadata and events based on a set of filters. Use one of three search methods:
 1. `parcl_ids`
 2. `parcl_property_ids`
-3. `location` (must provide latitude, longitude, and radius)
+3. `geo_coordinates` (must provide latitude, longitude, and radius)
 
 ```python
 results, filter_data = client.property_v2.search.retrieve(
+    # parcl_ids=[5495449],
     parcl_property_ids=[78353317, 135921544],
+    # geo_coordinates= {"latitude": 36.159445, "longitude": -86.483244, radius: 1},
     event_names=["LISTED_RENT"],
     is_new_construction=False,
     max_event_date="2024-12-31",

parcllabs/__version__.py

@@ -1 +1 @@
-VERSION = "1.14.0"
+VERSION = "1.14.1"

parcllabs/services/properties/property_v2.py

@@ -144,7 +144,7 @@ def _build_search_criteria(
         self,
         parcl_ids: list[int] | None = None,
         parcl_property_ids: list[int] | None = None,
-        location: dict[str, float] | None = None,
+        geo_coordinates: dict[str, float] | None = None,
     ) -> dict[str, Any]:
         """Build and validate search criteria."""
         data = {}
@@ -155,8 +155,8 @@ def _build_search_criteria(
         if parcl_property_ids:
             data["parcl_property_ids"] = parcl_property_ids
 
-        if location and all(k in location for k in ["latitude", "longitude", "radius"]):
-            data.update(location)
+        if geo_coordinates:
+            data["geo_coordinates"] = geo_coordinates
 
         return data
 
@@ -265,9 +265,7 @@ def retrieve(
         self,
         parcl_ids: list[int] | None = None,
         parcl_property_ids: list[int] | None = None,
-        latitude: float | None = None,
-        longitude: float | None = None,
-        radius: float | None = None,
+        geo_coordinates: dict[str, float] | None = None,
         property_types: list[str] | None = None,
         min_beds: int | None = None,
         max_beds: int | None = None,
@@ -300,9 +298,8 @@ def retrieve(
         Args:
             parcl_ids: List of parcl_ids to filter by.
             parcl_property_ids: List of parcl_property_ids to filter by.
-            latitude: Latitude to filter by.
-            longitude: Longitude to filter by.
-            radius: Radius to filter by.
+            geo_coordinates: Dictionary containing latitude, longitude, and radius (in miles)
+            to filter by.
             property_types: List of property types to filter by.
             min_beds: Minimum number of bedrooms to filter by.
             max_beds: Maximum number of bedrooms to filter by.
@@ -331,16 +328,11 @@ def retrieve(
         Returns:
             A pandas DataFrame containing the property data.
         """
-        # Build location dict if latitude, longitude and radius are provided
-        location = None
-        if all(v is not None for v in [latitude, longitude, radius]):
-            location = {"latitude": latitude, "longitude": longitude, "radius": radius}
-
         # Build search criteria
         data = self._build_search_criteria(
             parcl_ids=parcl_ids,
             parcl_property_ids=parcl_property_ids,
-            location=location,
+            geo_coordinates=geo_coordinates,
         )
 
         # Build filters using all provided parameters
@@ -350,12 +342,9 @@ def retrieve(
             "self",
             "parcl_ids",
             "parcl_property_ids",
-            "latitude",
-            "longitude",
-            "radius",
             "params",
             "data",
-            "location",
+            "geo_coordinates",
         ]:
             kwargs.pop(key, None)
 

tests/test_property_v2.py

@@ -52,20 +52,18 @@ def test_build_search_criteria(property_v2_service: PropertyV2Service) -> None:
     assert criteria == {"parcl_property_ids": [789, 101]}
 
     # Test with location
-    location = {"latitude": 37.7749, "longitude": -122.4194, "radius": 5.0}
-    criteria = property_v2_service._build_search_criteria(location=location)
-    assert criteria == location
+    geo_coordinates = {"latitude": 37.7749, "longitude": -122.4194, "radius": 5.0}
+    criteria = property_v2_service._build_search_criteria(geo_coordinates=geo_coordinates)
+    assert criteria == {"geo_coordinates": geo_coordinates}
 
     # Test with all parameters
     criteria = property_v2_service._build_search_criteria(
-        parcl_ids=[123], parcl_property_ids=[456], location=location
+        parcl_ids=[123], parcl_property_ids=[456], geo_coordinates=geo_coordinates
     )
     assert criteria == {
         "parcl_ids": [123],
         "parcl_property_ids": [456],
-        "latitude": 37.7749,
-        "longitude": -122.4194,
-        "radius": 5.0,
+        "geo_coordinates": geo_coordinates,
     }