Version bump to 0.8.12

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -84,7 +84,7 @@ properties = scrape_property(
 #### Sorting & Listing Types
 ```py
 # Sort options: list_price, list_date, sqft, beds, baths, last_update_date
-# Listing types: "for_sale", "for_rent", "sold", "pending", list, or None (all)
+# Listing types: "for_sale", "for_rent", "sold", "pending", "off_market", list, or None (common types)
 properties = scrape_property(
     location="Miami, FL",
     listing_type=["for_sale", "pending"],  # Single string, list, or None
@@ -94,6 +94,17 @@ properties = scrape_property(
 )
 ```
 
+#### Pagination Control
+```py
+# Sequential mode with early termination (more efficient for narrow filters)
+properties = scrape_property(
+    location="Los Angeles, CA",
+    listing_type="for_sale",
+    updated_in_past_hours=2,  # Narrow time window
+    parallel=False  # Fetch pages sequentially, stop when filters no longer match
+)
+```
+
 ## Output
 ```plaintext
 >>> properties.head()
@@ -129,30 +140,38 @@ for prop in properties[:5]:
 ```
 Required
 ├── location (str): Flexible location search - accepts any of these formats:
-    - ZIP code: "92104"
-    - City: "San Diego" or "San Francisco"
-    - City, State (abbreviated or full): "San Diego, CA" or "San Diego, California"
-    - Full address: "1234 Main St, San Diego, CA 92104"
-    - Neighborhood: "Downtown San Diego"
-    - County: "San Diego County"
-├── listing_type (option): Choose the type of listing.
-    - 'for_rent'
-    - 'for_sale'
-    - 'sold'
-    - 'pending' (for pending/contingent sales)
-
+│    - ZIP code: "92104"
+│    - City: "San Diego" or "San Francisco"
+│    - City, State (abbreviated or full): "San Diego, CA" or "San Diego, California"
+│    - Full address: "1234 Main St, San Diego, CA 92104"
+│    - Neighborhood: "Downtown San Diego"
+│    - County: "San Diego County"
+│    - State (no support for abbreviated): "California"
+│
+├── listing_type (str | list[str] | None): Choose the type of listing.
+│    - 'for_sale'
+│    - 'for_rent'
+│    - 'sold'
+│    - 'pending'
+│    - 'off_market'
+│    - 'new_community'
+│    - 'other'
+│    - 'ready_to_build'
+│    - List of strings returns properties matching ANY status: ['for_sale', 'pending']
+│    - None returns common listing types (for_sale, for_rent, sold, pending, off_market)
+│
 Optional
 ├── property_type (list): Choose the type of properties.
-    - 'single_family'
-    - 'multi_family'
-    - 'condos'
-    - 'condo_townhome_rowhome_coop'
-    - 'condo_townhome'
-    - 'townhomes'
-    - 'duplex_triplex'
-    - 'farm'
-    - 'land'
-    - 'mobile'
+│    - 'single_family'
+│    - 'multi_family'
+│    - 'condos'
+│    - 'condo_townhome_rowhome_coop'
+│    - 'condo_townhome'
+│    - 'townhomes'
+│    - 'duplex_triplex'
+│    - 'farm'
+│    - 'land'
+│    - 'mobile'
 │
 ├── return_type (option): Choose the return type.
 │    - 'pandas' (default)
@@ -165,12 +184,12 @@ Optional
 ├── past_days (integer): Number of past days to filter properties. Utilizes 'last_sold_date' for 'sold' listing types, and 'list_date' for others (for_rent, for_sale).
 │    Example: 30 (fetches properties listed/sold in the last 30 days)
 │
-├── past_hours (integer): Number of past hours to filter properties (more precise than past_days). Uses client-side filtering.
-│    Example: 24 (fetches properties from the last 24 hours)
+├── past_hours (integer | timedelta): Number of past hours to filter properties (more precise than past_days). Uses client-side filtering.
+│    Example: 24 or timedelta(hours=24) (fetches properties from the last 24 hours)
 │    Note: Cannot be used together with past_days or date_from/date_to
 │
 ├── date_from, date_to (string): Start and end dates to filter properties listed or sold, both dates are required.
-|    (use this to get properties in chunks as there's a 10k result limit)
+│    (use this to get properties in chunks as there's a 10k result limit)
 │    Accepts multiple formats with automatic precision detection:
 │    - Date strings: "YYYY-MM-DD" (day precision)
 │    - Datetime strings: "YYYY-MM-DDTHH:MM:SS" (hour precision, uses client-side filtering)
@@ -180,6 +199,14 @@ Optional
 │      Day precision: "2023-05-01", "2023-05-15"
 │      Hour precision: "2025-01-20T09:00:00", "2025-01-20T17:00:00"
 │
+├── updated_since (datetime | str): Filter properties updated since a specific date/time (based on last_update_date field)
+│    Accepts datetime objects or ISO 8601 strings
+│    Example: updated_since=datetime(2025, 11, 10, 9, 0) or "2025-11-10T09:00:00"
+│
+├── updated_in_past_hours (integer | timedelta): Filter properties updated in the past X hours (based on last_update_date field)
+│    Accepts integer (hours) or timedelta object
+│    Example: updated_in_past_hours=24 or timedelta(hours=24)
+│
 ├── beds_min, beds_max (integer): Filter by number of bedrooms
 │    Example: beds_min=2, beds_max=4 (2-4 bedrooms)
 │
@@ -199,7 +226,7 @@ Optional
 │    Example: year_built_min=2000, year_built_max=2024 (built between 2000-2024)
 │
 ├── sort_by (string): Sort results by field
-│    Options: 'list_date', 'sold_date', 'list_price', 'sqft', 'beds', 'baths'
+│    Options: 'list_date', 'sold_date', 'list_price', 'sqft', 'beds', 'baths', 'last_update_date'
 │    Example: sort_by='list_price'
 │
 ├── sort_direction (string): Sort direction, default is 'desc'
@@ -218,7 +245,9 @@ Optional
 │
 ├── limit (integer): Limit the number of properties to fetch. Max & default is 10000.
 │
-└── offset (integer): Starting position for pagination within the 10k limit. Use with limit to fetch results in chunks.
+├── offset (integer): Starting position for pagination within the 10k limit. Use with limit to fetch results in chunks.
+│
+└── parallel (True/False): Controls pagination strategy. Default is True (fetch pages in parallel for speed). Set to False for sequential fetching with early termination (useful for rate limiting or narrow time windows).
 ```
 
 ### Property Schema
@@ -265,6 +294,7 @@ Property
 │ ├── sold_price
 │ ├── last_sold_date  # datetime (full timestamp: YYYY-MM-DD HH:MM:SS)
 │ ├── last_status_change_date  # datetime (full timestamp: YYYY-MM-DD HH:MM:SS)
+│ ├── last_update_date  # datetime (full timestamp: YYYY-MM-DD HH:MM:SS)
 │ ├── last_sold_price
 │ ├── price_per_sqft
 │ ├── new_construction

homeharvest/__init__.py

@@ -48,6 +48,8 @@ def scrape_property(
     # New sorting parameters
     sort_by: str = None,
     sort_direction: str = "desc",
+    # Pagination control
+    parallel: bool = True,
 ) -> Union[pd.DataFrame, list[dict], list[Property]]:
     """
     Scrape properties from Realtor.com based on a given location and listing type.
@@ -72,6 +74,8 @@ def scrape_property(
         - date objects: date(2025, 1, 20) (day-level precision)
         - datetime objects: datetime(2025, 1, 20, 14, 30) (hour-level precision)
         The precision is automatically detected based on the input format.
+        Timezone handling: Naive datetimes are treated as local time and automatically converted to UTC.
+        Timezone-aware datetimes are converted to UTC. For best results, use timezone-aware datetimes.
     :param foreclosure: If set, fetches only foreclosure listings.
     :param extra_property_data: Increases requests by O(n). If set, this fetches additional property data (e.g. agent, broker, property evaluations etc.)
     :param exclude_pending: If true, this excludes pending or contingent properties from the results, unless listing type is pending.
@@ -80,7 +84,11 @@ def scrape_property(
 
     New parameters:
     :param past_hours: Get properties in the last _ hours (requires client-side filtering). Accepts int or timedelta.
-    :param updated_since: Filter by last_update_date (when property was last updated). Accepts datetime object or ISO 8601 string (client-side filtering)
+    :param updated_since: Filter by last_update_date (when property was last updated). Accepts datetime object or ISO 8601 string (client-side filtering).
+        Timezone handling: Naive datetimes (like datetime.now()) are treated as local time and automatically converted to UTC.
+        Timezone-aware datetimes are converted to UTC. Examples:
+        - datetime.now() - uses your local timezone
+        - datetime.now(timezone.utc) - uses UTC explicitly
     :param updated_in_past_hours: Filter by properties updated in the last _ hours. Accepts int or timedelta (client-side filtering)
     :param beds_min, beds_max: Filter by number of bedrooms
     :param baths_min, baths_max: Filter by number of bathrooms
@@ -90,6 +98,9 @@ def scrape_property(
     :param year_built_min, year_built_max: Filter by year built
     :param sort_by: Sort results by field (list_date, sold_date, list_price, sqft, beds, baths, last_update_date)
     :param sort_direction: Sort direction (asc, desc)
+    :param parallel: Controls pagination strategy. True (default) = fetch all pages in parallel for maximum speed.
+        False = fetch pages sequentially with early termination checks (useful for rate limiting or narrow time windows).
+        Sequential mode will stop paginating as soon as time-based filters indicate no more matches are possible.
 
     Note: past_days and past_hours also accept timedelta objects for more Pythonic usage.
     """
@@ -129,6 +140,22 @@ def scrape_property(
     converted_updated_since = convert_to_datetime_string(updated_since)
     converted_updated_in_past_hours = extract_timedelta_hours(updated_in_past_hours)
 
+    # Auto-apply optimal sort for time-based filters (unless user specified different sort)
+    if (converted_updated_since or converted_updated_in_past_hours) and not sort_by:
+        sort_by = "last_update_date"
+        if not sort_direction:
+            sort_direction = "desc"  # Most recent first
+
+    # Auto-apply optimal sort for PENDING listings with date filters
+    # PENDING API filtering is broken, so we rely on client-side filtering
+    # Sorting by pending_date ensures efficient pagination with early termination
+    elif (converted_listing_type == ListingType.PENDING and
+          (converted_past_days or converted_past_hours or converted_date_from) and
+          not sort_by):
+        sort_by = "pending_date"
+        if not sort_direction:
+            sort_direction = "desc"  # Most recent first
+
     scraper_input = ScraperInput(
         location=location,
         listing_type=converted_listing_type,
@@ -168,6 +195,8 @@ def scrape_property(
         # New sorting
         sort_by=sort_by,
         sort_direction=sort_direction,
+        # Pagination control
+        parallel=parallel,
     )
 
     site = RealtorScraper(scraper_input)

homeharvest/core/scrapers/__init__.py

@@ -55,6 +55,9 @@ class ScraperInput(BaseModel):
     sort_by: str | None = None
     sort_direction: str = "desc"
 
+    # Pagination control
+    parallel: bool = True
+
 
 class Scraper:
     session = None
@@ -70,35 +73,30 @@ class Scraper:
         if not self.session:
             Scraper.session = requests.Session()
             retries = Retry(
-                total=3, backoff_factor=4, status_forcelist=[429, 403], allowed_methods=frozenset(["GET", "POST"])
+                total=3, backoff_factor=4, status_forcelist=[429], allowed_methods=frozenset(["GET", "POST"])
             )
 
-            adapter = HTTPAdapter(max_retries=retries)
+            adapter = HTTPAdapter(max_retries=retries, pool_connections=10, pool_maxsize=20)
             Scraper.session.mount("http://", adapter)
             Scraper.session.mount("https://", adapter)
             Scraper.session.headers.update(
                 {
-                    "accept": "application/json, text/javascript",
-                    "accept-language": "en-US,en;q=0.9",
-                    "cache-control": "no-cache",
-                    "content-type": "application/json",
-                    "origin": "https://www.realtor.com",
-                    "pragma": "no-cache",
-                    "priority": "u=1, i",
-                    "rdc-ab-tests": "commute_travel_time_variation:v1",
-                    "sec-ch-ua": '"Not)A;Brand";v="99", "Google Chrome";v="127", "Chromium";v="127"',
-                    "sec-ch-ua-mobile": "?0",
-                    "sec-ch-ua-platform": '"Windows"',
-                    "sec-fetch-dest": "empty",
-                    "sec-fetch-mode": "cors",
-                    "sec-fetch-site": "same-origin",
-                    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
+                    'Content-Type': 'application/json',
+                    'apollographql-client-version': '26.11.1-26.11.1.1106489',
+                    'Accept': '*/*',
+                    'Accept-Language': 'en-US,en;q=0.9',
+                    'rdc-client-version': '26.11.1',
+                    'X-APOLLO-OPERATION-TYPE': 'query',
+                    'X-APOLLO-OPERATION-ID': 'null',
+                    'rdc-client-name': 'RDC_NATIVE_MOBILE-iPhone-com.move.Realtor',
+                    'apollographql-client-name': 'com.move.Realtor-apollo-ios',
+                    'User-Agent': 'Realtor.com/26.11.1.1106489 CFNetwork/3860.200.71 Darwin/25.1.0',
                 }
             )
 
-        if scraper_input.proxy:
-            proxy_url = scraper_input.proxy
-            proxies = {"http": proxy_url, "https": proxy_url}
+        self.proxy = scraper_input.proxy
+        if self.proxy:
+            proxies = {"http": self.proxy, "https": self.proxy}
             self.session.proxies.update(proxies)
 
         self.listing_type = scraper_input.listing_type
@@ -141,6 +139,9 @@ class Scraper:
         self.sort_by = scraper_input.sort_by
         self.sort_direction = scraper_input.sort_direction
 
+        # Pagination control
+        self.parallel = scraper_input.parallel
+
     def search(self) -> list[Union[Property | dict]]: ...
 
     @staticmethod

homeharvest/core/scrapers/realtor/__init__.py

@@ -8,6 +8,7 @@ This module implements the scraper for realtor.com
 from __future__ import annotations
 
 import json
+import re
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime
 from json import JSONDecodeError
@@ -21,12 +22,13 @@ from tenacity import (
 )
 
 from .. import Scraper
+from ....exceptions import AuthenticationError
 from ..models import (
     Property,
     ListingType,
     ReturnType
 )
-from .queries import GENERAL_RESULTS_QUERY, SEARCH_HOMES_DATA, HOMES_DATA, HOME_FRAGMENT
+from .queries import GENERAL_RESULTS_QUERY, SEARCH_HOMES_DATA, HOMES_DATA, HOME_FRAGMENT, SEARCH_RESULTS_FRAGMENT, LISTING_PHOTOS_FRAGMENT, MORPHEUS_SUGGESTIONS_QUERY
 from .processors import (
     process_property,
     process_extra_property_details,
@@ -35,64 +37,120 @@ from .processors import (
 
 
 class RealtorScraper(Scraper):
-    SEARCH_GQL_URL = "https://www.realtor.com/api/v1/rdc_search_srp?client_id=rdc-search-new-communities&schema=vesta"
-    PROPERTY_URL = "https://www.realtor.com/realestateandhomes-detail/"
-    PROPERTY_GQL = "https://graph.realtor.com/graphql"
-    ADDRESS_AUTOCOMPLETE_URL = "https://parser-external.geo.moveaws.com/suggest"
+    SEARCH_GQL_URL = "https://api.frontdoor.realtor.com/graphql"
     NUM_PROPERTY_WORKERS = 20
     DEFAULT_PAGE_SIZE = 200
 
     def __init__(self, scraper_input):
         super().__init__(scraper_input)
 
-    def handle_location(self):
-        # Get client_id from listing_type
-        if self.listing_type is None:
-            client_id = "for-sale"
-        elif isinstance(self.listing_type, list):
-            client_id = self.listing_type[0].value.lower().replace("_", "-") if self.listing_type else "for-sale"
-        else:
-            client_id = self.listing_type.value.lower().replace("_", "-")
+    @staticmethod
+    def _minify_query(query: str) -> str:
+        """Minify GraphQL query by collapsing whitespace to single spaces."""
+        # Split on whitespace, filter empty strings, join with single space
+        return ' '.join(query.split())
 
-        params = {
-            "input": self.location,
-            "client_id": client_id,
-            "limit": "1",
-            "area_types": "city,state,county,postal_code,address,street,neighborhood,school,school_district,university,park",
+    def _graphql_post(self, query: str, variables: dict, operation_name: str) -> dict:
+        """
+        Execute a GraphQL query with operation-specific headers.
+
+        Args:
+            query: GraphQL query string (must include operationName matching operation_name param)
+            variables: Query variables dictionary
+            operation_name: Name of the GraphQL operation for Apollo headers
+
+        Returns:
+            Response JSON dictionary
+        """
+        # Set operation-specific header (must match query's operationName)
+        self.session.headers['X-APOLLO-OPERATION-NAME'] = operation_name
+
+        payload = {
+            "operationName": operation_name,  # Include in payload
+            "query": self._minify_query(query),
+            "variables": variables,
         }
 
-        response = self.session.get(
-            self.ADDRESS_AUTOCOMPLETE_URL,
-            params=params,
+        response = self.session.post(self.SEARCH_GQL_URL, data=json.dumps(payload, separators=(',', ':')))
+
+        if response.status_code == 403:
+            if not self.proxy:
+                raise AuthenticationError(
+                    "Received 403 Forbidden from Realtor.com API.",
+                    response=response
                 )
-        response_json = response.json()
+            else:
+                raise Exception("Received 403 Forbidden, retrying...")
 
-        result = response_json["autocomplete"]
+        return response.json()
 
-        if not result:
+    @retry(
+        retry=retry_if_exception_type(Exception),
+        wait=wait_exponential(multiplier=1, min=1, max=4),
+        stop=stop_after_attempt(3),
+    )
+    def handle_location(self):
+        variables = {
+            "searchInput": {
+                "search_term": self.location
+            }
+        }
+
+        response_json = self._graphql_post(MORPHEUS_SUGGESTIONS_QUERY, variables, "GetMorpheusSuggestions")
+
+        if (
+            response_json is None
+            or "data" not in response_json
+            or response_json["data"] is None
+            or "search_suggestions" not in response_json["data"]
+            or response_json["data"]["search_suggestions"] is None
+            or "geo_results" not in response_json["data"]["search_suggestions"]
+            or not response_json["data"]["search_suggestions"]["geo_results"]
+        ):
+            # If we got a 400 error with "Required parameter is missing", raise to trigger retry
+            if response_json and "errors" in response_json:
+                error_msgs = [e.get("message", "") for e in response_json.get("errors", [])]
+                if any("Required parameter is missing" in msg for msg in error_msgs):
+                    raise Exception(f"Transient API error: {error_msgs}")
             return None
 
-        return result[0]
+        geo_result = response_json["data"]["search_suggestions"]["geo_results"][0]
+        geo = geo_result.get("geo", {})
+
+        result = {
+            "text": geo_result.get("text"),
+            "area_type": geo.get("area_type"),
+            "city": geo.get("city"),
+            "state_code": geo.get("state_code"),
+            "postal_code": geo.get("postal_code"),
+            "county": geo.get("county"),
+            "centroid": geo.get("centroid"),
+        }
+
+        if geo.get("area_type") == "address":
+            geo_id = geo.get("_id", "")
+            if geo_id.startswith("addr:"):
+                result["mpr_id"] = geo_id.replace("addr:", "")
+
+        return result
 
     def get_latest_listing_id(self, property_id: str) -> str | None:
-        query = """query Property($property_id: ID!) {
-                    property(id: $property_id) {
-                        listings {
+        query = """
+                fragment ListingFragment on Listing {
                     listing_id
                     primary
                 }
+                query GetPropertyListingId($property_id: ID!) {
+                    property(id: $property_id) {
+                        listings {
+                            ...ListingFragment
+                        }
                     }
                 }
                 """
 
         variables = {"property_id": property_id}
-        payload = {
-            "query": query,
-            "variables": variables,
-        }
-
-        response = self.session.post(self.SEARCH_GQL_URL, json=payload)
-        response_json = response.json()
+        response_json = self._graphql_post(query, variables, "GetPropertyListingId")
 
         property_info = response_json["data"]["property"]
         if property_info["listings"] is None:
@@ -108,31 +166,43 @@ class RealtorScraper(Scraper):
             return property_info["listings"][0]["listing_id"]
 
     def handle_home(self, property_id: str) -> list[Property]:
+        """Fetch single home with proper error handling."""
         query = (
-            """query Home($property_id: ID!) {
-                    home(property_id: $property_id) %s
+            """%s
+                query GetHomeDetails($property_id: ID!) {
+                    home(property_id: $property_id) {
+                        ...HomeDetailsFragment
+                    }
                 }"""
-            % HOMES_DATA
+            % HOME_FRAGMENT
         )
 
         variables = {"property_id": property_id}
-        payload = {
-            "query": query,
-            "variables": variables,
-        }
 
-        response = self.session.post(self.SEARCH_GQL_URL, json=payload)
-        response_json = response.json()
+        try:
+            data = self._graphql_post(query, variables, "GetHomeDetails")
 
-        property_info = response_json["data"]["home"]
+            # Check for errors or missing data
+            if "errors" in data or "data" not in data:
+                return []
 
+            if data["data"] is None or "home" not in data["data"]:
+                return []
+
+            property_info = data["data"]["home"]
+            if property_info is None:
+                return []
+
+            # Process based on return type
             if self.return_type != ReturnType.raw:
                 return [process_property(property_info, self.mls_only, self.extra_property_data,
-                                   self.exclude_pending, self.listing_type, get_key, process_extra_property_details)]
+                                       self.exclude_pending, self.listing_type, get_key,
+                                       process_extra_property_details)]
             else:
                 return [property_info]
 
-
+        except Exception:
+            return []
 
     def general_search(self, variables: dict, search_type: str) -> Dict[str, Union[int, Union[list[Property], list[dict]]]]:
         """
@@ -144,7 +214,15 @@ class RealtorScraper(Scraper):
         # Determine date field based on listing type
         # Convert listing_type to list for uniform handling
         if self.listing_type is None:
-            listing_types = []
+            # When None, return all common listing types as documented
+            # Note: NEW_COMMUNITY, OTHER, and READY_TO_BUILD are excluded as they typically return no results
+            listing_types = [
+                ListingType.FOR_SALE,
+                ListingType.FOR_RENT,
+                ListingType.SOLD,
+                ListingType.PENDING,
+                ListingType.OFF_MARKET,
+            ]
             date_field = None  # When no listing_type is specified, skip date filtering
         elif isinstance(self.listing_type, list):
             listing_types = self.listing_type
@@ -277,10 +355,14 @@ class RealtorScraper(Scraper):
         else:
             sort_param = ""  #: prioritize normal fractal sort from realtor
 
-        # Handle PENDING with or_filters (applies if PENDING is in the list or is the single type)
+        # Handle PENDING with or_filters
+        # Only use or_filters when PENDING is the only type or mixed only with FOR_SALE
+        # Using or_filters with other types (SOLD, FOR_RENT, etc.) will exclude those types
         has_pending = ListingType.PENDING in listing_types
+        other_types = [lt for lt in listing_types if lt not in [ListingType.PENDING, ListingType.FOR_SALE]]
+        use_or_filters = has_pending and len(other_types) == 0
         pending_or_contingent_param = (
-            "or_filters: { contingent: true, pending: true }" if has_pending else ""
+            "or_filters: { contingent: true, pending: true }" if use_or_filters else ""
         )
 
         # Build bucket parameter (only use fractal sort if no custom sort is specified)
@@ -317,12 +399,12 @@ class RealtorScraper(Scraper):
             is_foreclosure = "foreclosure: false"
 
         if search_type == "comps":  #: comps search, came from an address
-            query = """query Property_search(
+            query = """query GetHomeSearch(
                     $coordinates: [Float]!
                     $radius: String!
                     $offset: Int!,
                     ) {
-                        home_search(
+                        homeSearch: home_search(
                             query: {
                                 %s
                                 nearby: {
@@ -339,7 +421,9 @@ class RealtorScraper(Scraper):
                             limit: 200
                             offset: $offset
                     ) %s
-                }""" % (
+                }
+                %s
+                %s""" % (
                 is_foreclosure,
                 status_param,
                 date_param,
@@ -348,22 +432,18 @@ class RealtorScraper(Scraper):
                 pending_or_contingent_param,
                 sort_param,
                 GENERAL_RESULTS_QUERY,
+                SEARCH_RESULTS_FRAGMENT,
+                LISTING_PHOTOS_FRAGMENT,
             )
         elif search_type == "area":  #: general search, came from a general location
-            query = """query Home_search(
-                                $city: String,
-                                $county: [String],
-                                $state_code: String,
-                                $postal_code: String
+            query = """query GetHomeSearch(
+                                $search_location: SearchLocation,
                                 $offset: Int,
                             ) {
-                                home_search(
+                                homeSearch: home_search(
                                     query: {
                                         %s
-                                        city: $city
-                                        county: $county
-                                        postal_code: $postal_code
-                                        state_code: $state_code
+                                        search_location: $search_location
                                         %s
                                         %s
                                         %s
@@ -375,7 +455,9 @@ class RealtorScraper(Scraper):
                                     limit: 200
                                     offset: $offset
                                 ) %s
-                            }""" % (
+                            }
+                            %s
+                            %s""" % (
                 is_foreclosure,
                 status_param,
                 date_param,
@@ -385,32 +467,30 @@ class RealtorScraper(Scraper):
                 bucket_param,
                 sort_param,
                 GENERAL_RESULTS_QUERY,
+                SEARCH_RESULTS_FRAGMENT,
+                LISTING_PHOTOS_FRAGMENT,
             )
         else:  #: general search, came from an address
             query = (
-                """query Property_search(
+                """query GetHomeSearch(
                         $property_id: [ID]!
                         $offset: Int!,
                     ) {
-                        home_search(
+                        homeSearch: home_search(
                             query: {
                                 property_id: $property_id
                             }
                             limit: 1
                             offset: $offset
                         ) %s
-                    }"""
-                % GENERAL_RESULTS_QUERY
+                    }
+                    %s
+                    %s"""
+                % (GENERAL_RESULTS_QUERY, SEARCH_RESULTS_FRAGMENT, LISTING_PHOTOS_FRAGMENT)
             )
 
-        payload = {
-            "query": query,
-            "variables": variables,
-        }
-
-        response = self.session.post(self.SEARCH_GQL_URL, json=payload)
-        response_json = response.json()
-        search_key = "home_search" if "home_search" in query else "property_search"
+        response_json = self._graphql_post(query, variables, "GetHomeSearch")
+        search_key = "homeSearch"
 
         properties: list[Union[Property, dict]] = []
 
@@ -499,24 +579,16 @@ class RealtorScraper(Scraper):
                 if not location_info.get("centroid"):
                     return []
 
-                coordinates = list(location_info["centroid"].values())
+                centroid = location_info["centroid"]
+                coordinates = [centroid["lon"], centroid["lat"]]  # GeoJSON order: [lon, lat]
                 search_variables |= {
                     "coordinates": coordinates,
                     "radius": "{}mi".format(self.radius),
                 }
 
-        elif location_type == "postal_code":
+        else:  #: general search (city, county, postal_code, etc.)
             search_variables |= {
-                "postal_code": location_info.get("postal_code"),
-            }
-
-        else:  #: general search, location
-            search_variables |= {
-                "city": location_info.get("city"),
-                "county": location_info.get("county"),
-                "state_code": location_info.get("state_code"),
-                "postal_code": location_info.get("postal_code"),
-
+                "search_location": {"location": location_info.get("text")},
             }
 
         if self.foreclosure:
@@ -526,9 +598,11 @@ class RealtorScraper(Scraper):
         total = result["total"]
         homes = result["properties"]
 
+        # Fetch remaining pages based on parallel parameter
+        if self.offset + self.DEFAULT_PAGE_SIZE < min(total, self.offset + self.limit):
+            if self.parallel:
+                # Parallel mode: Fetch all remaining pages in parallel
                 with ThreadPoolExecutor() as executor:
-            # Store futures with their offsets to maintain proper sort order
-            # Start from offset + page_size and go up to offset + limit
                     futures_with_offsets = [
                         (i, executor.submit(
                             self.general_search,
@@ -542,15 +616,31 @@ class RealtorScraper(Scraper):
                         )
                     ]
 
-            # Collect results and sort by offset to preserve API sort order across pages
+                    # Collect results and sort by offset to preserve API sort order
                     results = []
                     for offset, future in futures_with_offsets:
                         results.append((offset, future.result()["properties"]))
 
-            # Sort by offset and concatenate in correct order
                     results.sort(key=lambda x: x[0])
                     for offset, properties in results:
                         homes.extend(properties)
+            else:
+                # Sequential mode: Fetch pages one by one with early termination checks
+                for current_offset in range(
+                    self.offset + self.DEFAULT_PAGE_SIZE,
+                    min(total, self.offset + self.limit),
+                    self.DEFAULT_PAGE_SIZE,
+                ):
+                    # Check if we should continue based on time-based filters
+                    if not self._should_fetch_more_pages(homes):
+                        break
+
+                    result = self.general_search(
+                        variables=search_variables | {"offset": current_offset},
+                        search_type=search_type,
+                    )
+                    page_properties = result["properties"]
+                    homes.extend(page_properties)
 
         # Apply client-side hour-based filtering if needed
         # (API only supports day-level filtering, so we post-filter for hour precision)
@@ -747,13 +837,14 @@ class RealtorScraper(Scraper):
         if not homes:
             return homes
 
-        from datetime import datetime, timedelta
+        from datetime import datetime, timedelta, timezone
 
         # Determine date range for last_update_date filtering
         date_range = None
 
         if self.updated_in_past_hours:
-            cutoff_datetime = datetime.now() - timedelta(hours=self.updated_in_past_hours)
+            # Use UTC now, strip timezone to match naive property dates
+            cutoff_datetime = (datetime.now(timezone.utc) - timedelta(hours=self.updated_in_past_hours)).replace(tzinfo=None)
             date_range = {'type': 'since', 'date': cutoff_datetime}
         elif self.updated_since:
             try:
@@ -784,15 +875,19 @@ class RealtorScraper(Scraper):
 
     def _get_date_range(self):
         """Get the date range for filtering based on instance parameters."""
-        from datetime import datetime, timedelta
+        from datetime import datetime, timedelta, timezone
 
         if self.last_x_days:
-            cutoff_date = datetime.now() - timedelta(days=self.last_x_days)
+            # Use UTC now, strip timezone to match naive property dates
+            cutoff_date = (datetime.now(timezone.utc) - timedelta(days=self.last_x_days)).replace(tzinfo=None)
             return {'type': 'since', 'date': cutoff_date}
         elif self.date_from and self.date_to:
             try:
-                from_date = datetime.fromisoformat(self.date_from)
-                to_date = datetime.fromisoformat(self.date_to)
+                # Parse and strip timezone to match naive property dates
+                from_date_str = self.date_from.replace('Z', '+00:00') if self.date_from.endswith('Z') else self.date_from
+                to_date_str = self.date_to.replace('Z', '+00:00') if self.date_to.endswith('Z') else self.date_to
+                from_date = datetime.fromisoformat(from_date_str).replace(tzinfo=None)
+                to_date = datetime.fromisoformat(to_date_str).replace(tzinfo=None)
                 return {'type': 'range', 'from_date': from_date, 'to_date': to_date}
             except ValueError:
                 return None
@@ -844,6 +939,74 @@ class RealtorScraper(Scraper):
             return date_range['from_date'] <= date_obj <= date_range['to_date']
         return False
 
+    def _should_fetch_more_pages(self, first_page):
+        """Determine if we should continue pagination based on first page results.
+
+        This optimization prevents unnecessary API calls when using time-based filters
+        with date sorting. If the last property on page 1 is already outside the time
+        window, all future pages will also be outside (due to sort order).
+
+        Args:
+            first_page: List of properties from the first page
+
+        Returns:
+            bool: True if we should continue pagination, False to stop early
+        """
+        from datetime import datetime, timedelta, timezone
+
+        # Check for last_update_date filters
+        if (self.updated_since or self.updated_in_past_hours) and self.sort_by == "last_update_date":
+            if not first_page:
+                return False
+
+            last_property = first_page[-1]
+            last_date = self._extract_date_from_home(last_property, 'last_update_date')
+
+            if not last_date:
+                return True
+
+            # Build date range for last_update_date filter
+            if self.updated_since:
+                try:
+                    cutoff_datetime = datetime.fromisoformat(self.updated_since.replace('Z', '+00:00') if self.updated_since.endswith('Z') else self.updated_since)
+                    # Strip timezone to match naive datetimes from _parse_date_value
+                    cutoff_datetime = cutoff_datetime.replace(tzinfo=None)
+                    date_range = {'type': 'since', 'date': cutoff_datetime}
+                except ValueError:
+                    return True
+            elif self.updated_in_past_hours:
+                # Use UTC now, strip timezone to match naive property dates
+                cutoff_datetime = (datetime.now(timezone.utc) - timedelta(hours=self.updated_in_past_hours)).replace(tzinfo=None)
+                date_range = {'type': 'since', 'date': cutoff_datetime}
+            else:
+                return True
+
+            return self._is_datetime_in_range(last_date, date_range)
+
+        # Check for PENDING date filters
+        if (self.listing_type == ListingType.PENDING and
+            (self.last_x_days or self.past_hours or self.date_from) and
+            self.sort_by == "pending_date"):
+
+            if not first_page:
+                return False
+
+            last_property = first_page[-1]
+            last_date = self._extract_date_from_home(last_property, 'pending_date')
+
+            if not last_date:
+                return True
+
+            # Build date range for pending date filter
+            date_range = self._get_date_range()
+            if not date_range:
+                return True
+
+            return self._is_datetime_in_range(last_date, date_range)
+
+        # No optimization applicable, continue pagination
+        return True
+
     def _apply_sort(self, homes):
         """Apply client-side sorting to ensure results are properly ordered.
 
@@ -862,6 +1025,8 @@ class RealtorScraper(Scraper):
 
         def get_sort_key(home):
             """Extract the sort field value from a home (handles both dict and Property object)."""
+            from datetime import datetime
+
             if isinstance(home, dict):
                 value = home.get(self.sort_by)
             else:
@@ -877,20 +1042,23 @@ class RealtorScraper(Scraper):
             if self.sort_by in ['list_date', 'sold_date', 'pending_date', 'last_update_date']:
                 if isinstance(value, str):
                     try:
-                        from datetime import datetime
                         # Handle timezone indicators
                         date_value = value
                         if date_value.endswith('Z'):
                             date_value = date_value[:-1] + '+00:00'
                         parsed_date = datetime.fromisoformat(date_value)
-                        return (0, parsed_date)
+                        # Normalize to timezone-naive for consistent comparison
+                        return 0, parsed_date.replace(tzinfo=None)
                     except (ValueError, AttributeError):
                         # If parsing fails, treat as None
                         return (1, 0) if self.sort_direction == "desc" else (1, float('inf'))
-                return (0, value)
+                # Handle datetime objects directly (normalize timezone)
+                if isinstance(value, datetime):
+                    return 0, value.replace(tzinfo=None)
+                return 0, value
 
             # For numeric fields, ensure we can compare
-            return (0, value)
+            return 0, value
 
         # Sort the homes
         reverse = (self.sort_direction == "desc")
@@ -942,8 +1110,8 @@ class RealtorScraper(Scraper):
 
 
     @retry(
-        retry=retry_if_exception_type(JSONDecodeError),
-        wait=wait_exponential(min=4, max=10),
+        retry=retry_if_exception_type((JSONDecodeError, Exception)),
+        wait=wait_exponential(multiplier=1, min=1, max=10),
         stop=stop_after_attempt(3),
     )
     def get_bulk_prop_details(self, property_ids: list[str]) -> dict:
@@ -956,24 +1124,27 @@ class RealtorScraper(Scraper):
 
         property_ids = list(set(property_ids))
 
-        # Construct the bulk query
         fragments = "\n".join(
-            f'home_{property_id}: home(property_id: {property_id}) {{ ...HomeData }}'
+            f'home_{property_id}: home(property_id: {property_id}) {{ ...HomeDetailsFragment }}'
             for property_id in property_ids
         )
         query = f"""{HOME_FRAGMENT}
 
-        query GetHomes {{
+query GetHomeDetails {{
     {fragments}
-        }}"""
+}}"""
 
-        response = self.session.post(self.SEARCH_GQL_URL, json={"query": query})
-        data = response.json()
+        data = self._graphql_post(query, {}, "GetHomeDetails")
 
-        if "data" not in data:
+        if "data" not in data or data["data"] is None:
+            # If we got a 400 error with "Required parameter is missing", raise to trigger retry
+            if data and "errors" in data:
+                error_msgs = [e.get("message", "") for e in data.get("errors", [])]
+                if any("Required parameter is missing" in msg for msg in error_msgs):
+                    raise Exception(f"Transient API error: {error_msgs}")
             return {}
 
         properties = data["data"]
-        return {data.replace('home_', ''): properties[data] for data in properties if properties[data]}
+        return {key.replace('home_', ''): properties[key] for key in properties if properties[key]}
 
 

homeharvest/core/scrapers/realtor/queries.py

@@ -1,3 +1,193 @@
+SEARCH_RESULTS_FRAGMENT = """
+fragment SearchFragment on SearchHome {
+    __typename
+    pending_date
+    listing_id
+    property_id
+    href
+    permalink
+    list_date
+    status
+    mls_status
+    last_sold_price
+    last_sold_date
+    last_status_change_date
+    last_update_date
+    list_price
+    list_price_max
+    list_price_min
+    price_per_sqft
+    tags
+    open_houses {
+        start_date
+        end_date
+        description
+        time_zone
+        dst
+        href
+        methods
+    }
+    details {
+        category
+        text
+        parent_category
+    }
+    pet_policy {
+        cats
+        dogs
+        dogs_small
+        dogs_large
+        __typename
+    }
+    units {
+        availability {
+          date
+          __typename
+        }
+        description {
+          baths_consolidated
+          baths
+          beds
+          sqft
+          __typename
+        }
+        photos(https: true) {
+            title
+            href
+            tags {
+                label
+            }
+        }
+        list_price
+        __typename
+    }
+    flags {
+        is_contingent
+        is_pending
+        is_new_construction
+    }
+    description {
+        type
+        sqft
+        beds
+        baths_full
+        baths_half
+        lot_sqft
+        year_built
+        garage
+        type
+        name
+        stories
+        text
+    }
+    source {
+        id
+        listing_id
+    }
+    hoa {
+        fee
+    }
+    location {
+        address {
+            street_direction
+            street_number
+            street_name
+            street_suffix
+            line
+            unit
+            city
+            state_code
+            postal_code
+            coordinate {
+                lon
+                lat
+            }
+        }
+        county {
+            name
+            fips_code
+        }
+        neighborhoods {
+            name
+        }
+    }
+    tax_record {
+        cl_id
+        public_record_id
+        last_update_date
+        apn
+        tax_parcel_id
+    }
+    primary_photo(https: true) {
+        href
+    }
+    advertisers {
+        email
+        broker {
+            name
+            fulfillment_id
+        }
+        type
+        name
+        fulfillment_id
+        builder {
+            name
+            fulfillment_id
+        }
+        phones {
+            ext
+            primary
+            type
+            number
+        }
+        office {
+            name
+            email
+            fulfillment_id
+            href
+            phones {
+                number
+                type
+                primary
+                ext
+            }
+            mls_set
+        }
+        corporation {
+            specialties
+            name
+            bio
+            href
+            fulfillment_id
+        }
+        mls_set
+        nrds_id
+        state_license
+        rental_corporation {
+            fulfillment_id
+        }
+        rental_management {
+            name
+            href
+            fulfillment_id
+        }
+    }
+    current_estimates {
+        __typename
+        source {
+            __typename
+            type
+            name
+        }
+        estimate
+        estimateHigh: estimate_high
+        estimateLow: estimate_low
+        date
+        isBestHomeValue: isbest_homevalue
+    }
+}
+"""
+
 _SEARCH_HOMES_DATA_BASE = """{
     pending_date
     listing_id
@@ -181,8 +371,189 @@ _SEARCH_HOMES_DATA_BASE = """{
 
 
 HOME_FRAGMENT = """
-fragment HomeData on Home {
+fragment HomeDetailsFragment on Home {
+    __typename
+    pending_date
+    listing_id
     property_id
+    href
+    permalink
+    list_date
+    status
+    mls_status
+    last_sold_price
+    last_sold_date
+    last_status_change_date
+    last_update_date
+    list_price
+    list_price_max
+    list_price_min
+    price_per_sqft
+    tags
+    open_houses {
+        start_date
+        end_date
+        description
+        time_zone
+        dst
+        href
+        methods
+    }
+    details {
+        category
+        text
+        parent_category
+    }
+    pet_policy {
+        cats
+        dogs
+        dogs_small
+        dogs_large
+        __typename
+    }
+    units {
+        availability {
+          date
+          __typename
+        }
+        description {
+          baths_consolidated
+          baths
+          beds
+          sqft
+          __typename
+        }
+        photos(https: true) {
+            title
+            href
+            tags {
+                label
+            }
+        }
+        list_price
+        __typename
+    }
+    flags {
+        is_contingent
+        is_pending
+        is_new_construction
+    }
+    description {
+        type
+        sqft
+        beds
+        baths_full
+        baths_half
+        lot_sqft
+        year_built
+        garage
+        type
+        name
+        stories
+        text
+    }
+    source {
+        id
+        listing_id
+    }
+    hoa {
+        fee
+    }
+    location {
+        address {
+            street_direction
+            street_number
+            street_name
+            street_suffix
+            line
+            unit
+            city
+            state_code
+            postal_code
+            coordinate {
+                lon
+                lat
+            }
+        }
+        county {
+            name
+            fips_code
+        }
+        neighborhoods {
+            name
+        }
+        parcel {
+            parcel_id
+        }
+    }
+    tax_record {
+        cl_id
+        public_record_id
+        last_update_date
+        apn
+        tax_parcel_id
+    }
+    primary_photo(https: true) {
+        href
+    }
+    photos(https: true) {
+        title
+        href
+        tags {
+            label
+        }
+    }
+    advertisers {
+        email
+        broker {
+            name
+            fulfillment_id
+        }
+        type
+        name
+        fulfillment_id
+        builder {
+            name
+            fulfillment_id
+        }
+        phones {
+            ext
+            primary
+            type
+            number
+        }
+        office {
+            name
+            email
+            fulfillment_id
+            href
+            phones {
+                number
+                type
+                primary
+                ext
+            }
+            mls_set
+        }
+        corporation {
+            specialties
+            name
+            bio
+            href
+            fulfillment_id
+        }
+        mls_set
+        nrds_id
+        state_license
+        rental_corporation {
+            fulfillment_id
+        }
+        rental_management {
+            name
+            href
+            fulfillment_id
+        }
+    }
     nearbySchools: nearby_schools(radius: 5.0, limit_per_level: 3) {
         __typename schools { district { __typename id name } }
     }
@@ -198,11 +569,6 @@ fragment HomeData on Home {
             last_n_days
         }
     }
-    location {
-        parcel {
-            parcel_id
-        }
-    }
     taxHistory: tax_history { __typename tax year assessment { __typename building land total } }
     property_history {
         date
@@ -227,6 +593,18 @@ fragment HomeData on Home {
         text
         category
     }
+    estimates {
+        __typename
+        currentValues: current_values {
+            __typename
+            source { __typename type name }
+            estimate
+            estimateHigh: estimate_high
+            estimateLow: estimate_low
+            date
+            isBestHomeValue: isbest_homevalue
+        }
+    }
 }
 """
 
@@ -300,8 +678,38 @@ current_estimates {
 }
 }""" % _SEARCH_HOMES_DATA_BASE
 
-GENERAL_RESULTS_QUERY = """{
+# Query body using inline fields (kept for backward compatibility)
+GENERAL_RESULTS_QUERY_BODY = """{
                             count
                             total
                             results %s
                         }""" % SEARCH_HOMES_DATA
+
+GENERAL_RESULTS_QUERY = """{
+                            __typename
+                            count
+                            total
+                            results {
+                                __typename
+                                ...SearchFragment
+                                ...ListingPhotosFragment
+                            }
+                        }"""
+
+LISTING_PHOTOS_FRAGMENT = """
+fragment ListingPhotosFragment on SearchHome {
+    __typename
+    photos(https: true) {
+        __typename
+        title
+        href
+        tags {
+            __typename
+            label
+            probability
+        }
+    }
+}
+"""
+
+MORPHEUS_SUGGESTIONS_QUERY = """query GetMorpheusSuggestions($searchInput: SearchSuggestionsInput!) { search_suggestions(search_input: $searchInput) { __typename geo_results { __typename type text geo { __typename _id _score mpr_id area_type city state_code postal_code country lat lon county counties { __typename name fips state_code } slug_id geo_id score name city_slug_id centroid { __typename lat lon } county_needed_for_uniq street line school school_id school_district school_district_id has_catchment university university_id neighborhood park } } no_matches has_results filter_criteria { __typename property_type { __typename type } price { __typename min max pattern } bed { __typename min max pattern } bath { __typename min max pattern } feature_tags { __typename tags } listing_status { __typename new_construction existing_homes foreclosures recently_sold fifty_five_plus open_house hide_new_construction hide_existing_homes hide_foreclosures hide_recently_sold hide_fifty_five_plus hide_open_house virtual_tour three_d_tour contingent hide_contingent pending hide_pending } keyword { __typename keywords } garage { __typename min max pattern } age { __typename min max pattern } stories { __typename min max pattern } lot_size { __typename min max pattern } square_feet { __typename min max pattern } home_size { __typename min max pattern } basement finished_basement pool waterfront fireplace detached_garage expand { __typename radius } hoa { __typename type fee } } message_data { __typename property_type pool waterfront fireplace basement finished_basement detached_garage listing_status { __typename new_construction existing_homes foreclosures recently_sold fifty_five_plus open_house hide_new_construction hide_existing_homes hide_foreclosures hide_recently_sold hide_fifty_five_plus hide_open_house } keywords price { __typename min max pattern } bed { __typename min max pattern } bath { __typename min max pattern } garage { __typename min max pattern } stories { __typename min max pattern } age { __typename min max pattern } lot_size { __typename min max pattern } square_feet { __typename min max pattern } } original_string morpheus_context } }"""

homeharvest/utils.py

@@ -331,15 +331,26 @@ def validate_sort(sort_by: str | None, sort_direction: str | None = "desc") -> N
 
 def convert_to_datetime_string(value) -> str | None:
     """
-    Convert datetime object or string to ISO 8601 string format.
+    Convert datetime object or string to ISO 8601 string format with UTC timezone.
 
     Accepts:
-    - datetime.datetime objects
-    - datetime.date objects
+    - datetime.datetime objects (naive or timezone-aware)
+      - Naive datetimes are treated as local time and converted to UTC
+      - Timezone-aware datetimes are converted to UTC
+    - datetime.date objects (treated as midnight UTC)
     - ISO 8601 strings (returned as-is)
     - None (returns None)
 
-    Returns ISO 8601 formatted string or None.
+    Returns ISO 8601 formatted string with UTC timezone or None.
+
+    Examples:
+        >>> # Naive datetime (treated as local time)
+        >>> convert_to_datetime_string(datetime(2025, 1, 20, 14, 30))
+        '2025-01-20T22:30:00+00:00'  # Assuming PST (UTC-8)
+
+        >>> # Timezone-aware datetime
+        >>> convert_to_datetime_string(datetime(2025, 1, 20, 14, 30, tzinfo=timezone.utc))
+        '2025-01-20T14:30:00+00:00'
     """
     if value is None:
         return None
@@ -349,13 +360,23 @@ def convert_to_datetime_string(value) -> str | None:
         return value
 
     # datetime.datetime object
-    from datetime import datetime, date
+    from datetime import datetime, date, timezone
     if isinstance(value, datetime):
-        return value.isoformat()
+        # Handle naive datetime - treat as local time and convert to UTC
+        if value.tzinfo is None:
+            # Convert naive datetime to aware local time, then to UTC
+            local_aware = value.astimezone()
+            utc_aware = local_aware.astimezone(timezone.utc)
+            return utc_aware.isoformat()
+        else:
+            # Already timezone-aware, convert to UTC
+            utc_aware = value.astimezone(timezone.utc)
+            return utc_aware.isoformat()
 
-    # datetime.date object (convert to datetime at midnight)
+    # datetime.date object (convert to datetime at midnight UTC)
     if isinstance(value, date):
-        return datetime.combine(value, datetime.min.time()).isoformat()
+        utc_datetime = datetime.combine(value, datetime.min.time()).replace(tzinfo=timezone.utc)
+        return utc_datetime.isoformat()
 
     raise ValueError(
         f"Invalid datetime value. Expected datetime object, date object, or ISO 8601 string. "

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "homeharvest"
-version = "0.8.0"
+version = "0.8.12"
 description = "Real estate scraping library"
 authors = ["Zachary Hampton <zachary@bunsly.com>", "Cullen Watson <cullen@bunsly.com>"]
 homepage = "https://github.com/ZacharyHampton/HomeHarvest"

tests/test_realtor.py

@@ -1,3 +1,6 @@
+import pytz
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
 from homeharvest import scrape_property, Property
 import pandas as pd
 
@@ -85,6 +88,25 @@ def test_realtor_date_range_sold():
     )
 
 
+def test_listing_type_none_includes_sold():
+    """Test that listing_type=None includes sold listings (issue #142)"""
+    # Get properties with listing_type=None (should include all common types)
+    result_none = scrape_property(
+        location="Warren, MI",
+        listing_type=None
+    )
+
+    # Verify we got results
+    assert result_none is not None and len(result_none) > 0
+
+    # Verify sold listings are included
+    status_types = set(result_none['status'].unique())
+    assert 'SOLD' in status_types, "SOLD listings should be included when listing_type=None"
+
+    # Verify we get multiple listing types (not just one)
+    assert len(status_types) > 1, "Should return multiple listing types when listing_type=None"
+
+
 def test_realtor_single_property():
     results = [
         scrape_property(
@@ -286,6 +308,30 @@ def test_phone_number_matching():
     assert row["agent_phones"].values[0] == matching_row["agent_phones"].values[0]
 
 
+def test_parallel_search_consistency():
+    """Test that the same search executed 3 times in parallel returns consistent results"""
+    def search_task():
+        return scrape_property(
+            location="Phoenix, AZ",
+            listing_type="for_sale",
+            limit=100
+        )
+
+    with ThreadPoolExecutor(max_workers=3) as executor:
+        futures = [executor.submit(search_task) for _ in range(3)]
+        results = [future.result() for future in as_completed(futures)]
+
+    # Verify all results are valid
+    assert all([result is not None for result in results])
+    assert all([isinstance(result, pd.DataFrame) for result in results])
+    assert all([len(result) > 0 for result in results])
+
+    # Verify all results have the same length (primary consistency check)
+    lengths = [len(result) for result in results]
+    assert len(set(lengths)) == 1, \
+        f"All parallel searches should return same number of results, got lengths: {lengths}"
+
+
 def test_return_type():
     results = {
         "pandas": [scrape_property(location="Surprise, AZ", listing_type="for_rent", limit=100)],
@@ -1358,3 +1404,237 @@ def test_combined_filters_with_raw_data():
 
         assert mls_id is not None and mls_id != "", \
             f"Property {prop.get('property_id')} should have an MLS ID (source.id)"
+
+
+def test_updated_since_filtering():
+    """Test the updated_since parameter for filtering by last_update_date"""
+    from datetime import datetime, timedelta
+
+    # Test 1: Filter by last update in past 10 minutes (user's example)
+    cutoff_time = datetime.now() - timedelta(minutes=10)
+    result_10min = scrape_property(
+        location="California",
+        updated_since=cutoff_time,
+        sort_by="last_update_date",
+        sort_direction="desc",
+        limit=100
+    )
+
+    assert result_10min is not None
+    print(f"\n10-minute window returned {len(result_10min)} properties")
+
+    # Test 2: Verify all results have last_update_date within range
+    if len(result_10min) > 0:
+        for idx in range(min(10, len(result_10min))):
+            update_date_str = result_10min.iloc[idx]["last_update_date"]
+            if pd.notna(update_date_str):
+                try:
+                    # Handle timezone-aware datetime strings
+                    date_str = str(update_date_str)
+                    if '+' in date_str or date_str.endswith('Z'):
+                        # Remove timezone for comparison with naive cutoff_time
+                        date_str = date_str.replace('+00:00', '').replace('Z', '')
+                    update_date = datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
+
+                    assert update_date >= cutoff_time, \
+                        f"Property last_update_date {update_date} should be >= {cutoff_time}"
+                    print(f"Property {idx}: last_update_date = {update_date} (valid)")
+                except (ValueError, TypeError) as e:
+                    print(f"Warning: Could not parse date {update_date_str}: {e}")
+
+    # Test 3: Compare different time windows
+    result_1hour = scrape_property(
+        location="California",
+        updated_since=datetime.now() - timedelta(hours=1),
+        limit=50
+    )
+
+    result_24hours = scrape_property(
+        location="California",
+        updated_since=datetime.now() - timedelta(hours=24),
+        limit=50
+    )
+
+    print(f"1-hour window: {len(result_1hour)} properties")
+    print(f"24-hour window: {len(result_24hours)} properties")
+
+    # Longer time window should return same or more results
+    if len(result_1hour) > 0 and len(result_24hours) > 0:
+        assert len(result_1hour) <= len(result_24hours), \
+            "1-hour filter should return <= 24-hour results"
+
+    # Test 4: Verify sorting works with filtering
+    if len(result_10min) > 1:
+        # Get non-null dates
+        dates = []
+        for idx in range(len(result_10min)):
+            date_str = result_10min.iloc[idx]["last_update_date"]
+            if pd.notna(date_str):
+                try:
+                    # Handle timezone-aware datetime strings
+                    clean_date_str = str(date_str)
+                    if '+' in clean_date_str or clean_date_str.endswith('Z'):
+                        clean_date_str = clean_date_str.replace('+00:00', '').replace('Z', '')
+                    dates.append(datetime.strptime(clean_date_str, "%Y-%m-%d %H:%M:%S"))
+                except (ValueError, TypeError):
+                    pass
+
+        if len(dates) > 1:
+            # Check if sorted descending
+            for i in range(len(dates) - 1):
+                assert dates[i] >= dates[i + 1], \
+                    f"Results should be sorted by last_update_date descending: {dates[i]} >= {dates[i+1]}"
+
+
+def test_updated_since_optimization():
+    """Test that updated_since optimization works (auto-sort + early termination)"""
+    from datetime import datetime, timedelta
+    import time
+
+    # Test 1: Verify auto-sort is applied when using updated_since without explicit sort
+    start_time = time.time()
+    result = scrape_property(
+        location="California",
+        updated_since=datetime.now() - timedelta(minutes=5),
+        # NO sort_by specified - should auto-apply sort_by="last_update_date"
+        limit=50
+    )
+    elapsed_time = time.time() - start_time
+
+    print(f"\nAuto-sort test: {len(result)} properties in {elapsed_time:.2f}s")
+
+    # Should complete quickly due to early termination optimization (<5 seconds)
+    assert elapsed_time < 5.0, f"Query should be fast with optimization, took {elapsed_time:.2f}s"
+
+    # Verify results are sorted by last_update_date (proving auto-sort worked)
+    if len(result) > 1:
+        dates = []
+        for idx in range(min(10, len(result))):
+            date_str = result.iloc[idx]["last_update_date"]
+            if pd.notna(date_str):
+                try:
+                    clean_date_str = str(date_str)
+                    if '+' in clean_date_str or clean_date_str.endswith('Z'):
+                        clean_date_str = clean_date_str.replace('+00:00', '').replace('Z', '')
+                    dates.append(datetime.strptime(clean_date_str, "%Y-%m-%d %H:%M:%S"))
+                except (ValueError, TypeError):
+                    pass
+
+        if len(dates) > 1:
+            # Verify descending order (most recent first)
+            for i in range(len(dates) - 1):
+                assert dates[i] >= dates[i + 1], \
+                    "Auto-applied sort should order by last_update_date descending"
+
+    print("Auto-sort optimization verified ✓")
+
+
+def test_pending_date_optimization():
+    """Test that PENDING + date filters get auto-sort and early termination"""
+    from datetime import datetime, timedelta
+    import time
+
+    # Test: Verify auto-sort is applied for PENDING with past_days
+    start_time = time.time()
+    result = scrape_property(
+        location="California",
+        listing_type="pending",
+        past_days=7,
+        # NO sort_by specified - should auto-apply sort_by="pending_date"
+        limit=50
+    )
+    elapsed_time = time.time() - start_time
+
+    print(f"\nPENDING auto-sort test: {len(result)} properties in {elapsed_time:.2f}s")
+
+    # Should complete quickly due to optimization (<10 seconds)
+    assert elapsed_time < 10.0, f"PENDING query should be fast with optimization, took {elapsed_time:.2f}s"
+
+    # Verify results are sorted by pending_date (proving auto-sort worked)
+    if len(result) > 1:
+        dates = []
+        for idx in range(min(10, len(result))):
+            date_str = result.iloc[idx]["pending_date"]
+            if pd.notna(date_str):
+                try:
+                    clean_date_str = str(date_str)
+                    if '+' in clean_date_str or clean_date_str.endswith('Z'):
+                        clean_date_str = clean_date_str.replace('+00:00', '').replace('Z', '')
+                    dates.append(datetime.strptime(clean_date_str, "%Y-%m-%d %H:%M:%S"))
+                except (ValueError, TypeError):
+                    pass
+
+        if len(dates) > 1:
+            # Verify descending order (most recent first)
+            for i in range(len(dates) - 1):
+                assert dates[i] >= dates[i + 1], \
+                    "PENDING auto-applied sort should order by pending_date descending"
+
+    print("PENDING optimization verified ✓")
+
+
+def test_basic_last_update_date():
+    from datetime import datetime, timedelta
+
+    # Test with naive datetime (treated as local time)
+    now = datetime.now()
+
+    properties = scrape_property(
+        "California",
+        updated_since=now - timedelta(minutes=10),
+        sort_by="last_update_date",
+        sort_direction="desc"
+    )
+
+    # Convert now to timezone-aware for comparison with UTC dates in DataFrame
+    now_utc = now.astimezone(tz=pytz.timezone("UTC"))
+
+    # Check all last_update_date values are <= now
+    assert (properties["last_update_date"] <= now_utc).all()
+
+    # Verify we got some results
+    assert len(properties) > 0
+
+
+def test_timezone_aware_last_update_date():
+    """Test that timezone-aware datetimes work correctly for updated_since"""
+    from datetime import datetime, timedelta, timezone
+
+    # Test with timezone-aware datetime (explicit UTC)
+    now_utc = datetime.now(timezone.utc)
+
+    properties = scrape_property(
+        "California",
+        updated_since=now_utc - timedelta(minutes=10),
+        sort_by="last_update_date",
+        sort_direction="desc"
+    )
+
+    # Check all last_update_date values are <= now
+    assert (properties["last_update_date"] <= now_utc).all()
+
+    # Verify we got some results
+    assert len(properties) > 0
+
+
+def test_timezone_handling_date_range():
+    """Test timezone handling for date_from and date_to parameters"""
+    from datetime import datetime, timedelta
+
+    # Test with naive datetimes for date range (PENDING properties)
+    now = datetime.now()
+    three_days_ago = now - timedelta(days=3)
+
+    properties = scrape_property(
+        "California",
+        listing_type="pending",
+        date_from=three_days_ago,
+        date_to=now
+    )
+
+    # Verify we got results and they're within the date range
+    if len(properties) > 0:
+        # Convert now to UTC for comparison
+        now_utc = now.astimezone(tz=pytz.timezone("UTC"))
+        assert (properties["pending_date"] <= now_utc).all()
+