Add foreclosure parameter (#55)

fix: rent url

README.md

@@ -1,15 +1,11 @@
 <img src="https://github.com/ZacharyHampton/HomeHarvest/assets/78247585/d1a2bf8b-09f5-4c57-b33a-0ada8a34f12d" width="400">
 
-**HomeHarvest** is a simple, yet comprehensive, real estate scraping library that extracts and formats data in the style of MLS listings.
+**HomeHarvest** is a real estate scraping library that extracts and formats data in the style of MLS listings.
-
-[![Try with Replit](https://replit.com/badge?caption=Try%20with%20Replit)](https://replit.com/@ZacharyHampton/HomeHarvestDemo)
 
 **Not technical?** Try out the web scraping tool on our site at [tryhomeharvest.com](https://tryhomeharvest.com).
 
 *Looking to build a data-focused software product?* **[Book a call](https://bunsly.com)** *to work with us.*
 
-Check out another project we wrote: ***[JobSpy](https://github.com/Bunsly/JobSpy)** – a Python package for job scraping*
-
 ## HomeHarvest Features
 
 - **Source**: Fetches properties directly from **Realtor.com**.
@@ -17,8 +13,6 @@ Check out another project we wrote: ***[JobSpy](https://github.com/Bunsly/JobSpy
 - **Export Flexibility**: Options to save as either CSV or Excel.
 - **Usage Modes**:
   - **Python**: For those who'd like to integrate scraping into their Python scripts.
-  - **CLI**: For users who prefer command-line operations.
-
 
 [Video Guide for HomeHarvest](https://youtu.be/J1qgNPgmSLI) - _updated for release v0.3.4_
 
@@ -50,9 +44,9 @@ properties = scrape_property(
   
   # date_from="2023-05-01", # alternative to past_days 
   # date_to="2023-05-28", 
+  # foreclosure=True
   
   # mls_only=True,  # only fetch MLS listings
-  # proxy="http://user:pass@host:port"  # use a proxy to change your IP address
 )
 print(f"Number of properties: {len(properties)}")
 
@@ -61,7 +55,6 @@ properties.to_csv(filename, index=False)
 print(properties.head())
 ```
 
-
 ## Output
 ```plaintext
 >>> properties.head()
@@ -92,43 +85,15 @@ Optional
 │    Example: 30 (fetches properties listed/sold in the last 30 days)
 │
 ├── 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)
 │    Format for both must be "YYYY-MM-DD". 
 │    Example: "2023-05-01", "2023-05-15" (fetches properties listed/sold between these dates)
 │
 ├── mls_only (True/False): If set, fetches only MLS listings (mainly applicable to 'sold' listings)
 │
+├── foreclosure (True/False): If set, fetches only foreclosures
+│
 └── proxy (string): In format 'http://user:pass@host:port'
-
-
-```
-
-### CLI 
-
-```
-usage: homeharvest [-l {for_sale,for_rent,sold}] [-o {excel,csv}] [-f FILENAME] [-p PROXY] [-d DAYS] [-r RADIUS] [-m] [-c] location
-                                                                                                                             
-Home Harvest Property Scraper                                                                                                 
-                                                                                                                             
-positional arguments:                                                                                                         
-  location              Location to scrape (e.g., San Francisco, CA)                                                          
-                                                                                                                             
-options:                                                                                                                      
-  -l {for_sale,for_rent,sold,pending}, --listing_type {for_sale,for_rent,sold,pending}                                                        
-                        Listing type to scrape                                                                                
-  -o {excel,csv}, --output {excel,csv}                                                                                        
-                        Output format                                                                                         
-  -f FILENAME, --filename FILENAME                                                                                            
-                        Name of the output file (without extension)                                                           
-  -p PROXY, --proxy PROXY                                                                                                     
-                        Proxy to use for scraping                                                                             
-  -d DAYS, --days DAYS  Sold/listed in last _ days filter.                                                                           
-  -r RADIUS, --radius RADIUS                                                                                                  
-                        Get comparable properties within _ (e.g., 0.0) miles. Only applicable for individual addresses.        
-  -m, --mls_only        If set, fetches only MLS listings.                                                                    
-```
-```bash
-homeharvest "San Francisco, CA" -l for_rent -o excel -f HomeHarvest
 ```
 
 ### Property Schema
@@ -179,21 +144,4 @@ The following exceptions may be raised when using HomeHarvest:
 
 - `InvalidListingType` - valid options: `for_sale`, `for_rent`, `sold`
 - `InvalidDate` - date_from or date_to is not in the format YYYY-MM-DD
-  
+  
-  
-## Frequently Asked Questions
----
-
-**Q: Encountering issues with your searches?**  
-**A:** Try to broaden the parameters you're using. If problems persist, [submit an issue](https://github.com/ZacharyHampton/HomeHarvest/issues).
-
----
-
-**Q: Received a Forbidden 403 response code?**  
-**A:** This indicates that you have been blocked by Realtor.com for sending too many requests. We recommend:
-
-- Waiting a few seconds between requests.
-- Trying a VPN or useing a proxy as a parameter to scrape_property() to change your IP address.
-
----
-

homeharvest/__init__.py

@@ -15,6 +15,7 @@ def scrape_property(
     proxy: str = None,
     date_from: str = None,
     date_to: str = None,
+    foreclosure: bool = None,
 ) -> pd.DataFrame:
     """
     Scrape properties from Realtor.com based on a given location and listing type.
@@ -38,6 +39,7 @@ def scrape_property(
         last_x_days=past_days,
         date_from=date_from,
         date_to=date_to,
+        foreclosure=foreclosure,
     )
 
     site = RealtorScraper(scraper_input)

homeharvest/core/scrapers/__init__.py

@@ -13,6 +13,7 @@ class ScraperInput:
     last_x_days: int | None = None
     date_from: str | None = None
     date_to: str | None = None
+    foreclosure: bool | None = None
 
 
 class Scraper:
@@ -40,6 +41,7 @@ class Scraper:
         self.mls_only = scraper_input.mls_only
         self.date_from = scraper_input.date_from
         self.date_to = scraper_input.date_to
+        self.foreclosure = scraper_input.foreclosure
 
     def search(self) -> list[Property]:
         ...

homeharvest/core/scrapers/models.py

@@ -34,6 +34,8 @@ class Address:
 
 @dataclass
 class Description:
+    primary_photo: str | None = None
+    alt_photos: list[str] | None = None
     style: str | None = None
     beds: int | None = None
     baths_full: int | None = None

homeharvest/core/scrapers/realtor/__init__.py

@@ -84,6 +84,12 @@ class RealtorScraper(Scraper):
                             garage
                             permalink
                         }
+                        primary_photo {
+                            href
+                        }
+                        photos {
+                            href
+                        }
                     }
                 }"""
 
@@ -152,6 +158,8 @@ class RealtorScraper(Scraper):
             else None,
             address=self._parse_address(property_info, search_type="handle_listing"),
             description=Description(
+                primary_photo=property_info["primary_photo"].get("href", "").replace("s.jpg", "od-w480_h360_x2.webp?w=1080&q=75"),
+                alt_photos=self.process_alt_photos(property_info.get("photos", [])),
                 style=property_info["basic"].get("type", "").upper(),
                 beds=property_info["basic"].get("beds"),
                 baths_full=property_info["basic"].get("baths_full"),
@@ -247,6 +255,12 @@ class RealtorScraper(Scraper):
                             units
                             year_built
                         }
+                        primary_photo {
+                            href
+                        }
+                        photos {
+                            href
+                        }
                     }
                 }"""
 
@@ -334,6 +348,12 @@ class RealtorScraper(Scraper):
                                         name
                                     }
                                 }
+                                primary_photo {
+                                    href
+                                }
+                                photos {
+                                    href
+                                }
                             }
                         }
                     }"""
@@ -361,9 +381,16 @@ class RealtorScraper(Scraper):
             if self.listing_type == ListingType.PENDING
             else ""
         )
-
+ 
         listing_type = ListingType.FOR_SALE if self.listing_type == ListingType.PENDING else self.listing_type
-
+        is_foreclosure = ""
+        
+        if 'foreclosure' in variables and variables['foreclosure'] == True:
+               is_foreclosure = "foreclosure: true"
+        
+        if 'foreclosure' in variables and variables['foreclosure'] == False:
+             is_foreclosure = "foreclosure: false"
+        
         if search_type == "comps":  #: comps search, came from an address
             query = """query Property_search(
                     $coordinates: [Float]!
@@ -372,6 +399,7 @@ class RealtorScraper(Scraper):
                     ) {
                         home_search(
                             query: { 
+                                %s
                                 nearby: {
                                     coordinates: $coordinates
                                     radius: $radius 
@@ -384,6 +412,7 @@ class RealtorScraper(Scraper):
                             limit: 200
                             offset: $offset
                     ) %s""" % (
+                is_foreclosure,        
                 listing_type.value.lower(),
                 date_param,
                 pending_or_contingent_param,
@@ -400,6 +429,7 @@ class RealtorScraper(Scraper):
                             ) {
                                 home_search(
                                     query: {
+                                        %s
                                         city: $city
                                         county: $county
                                         postal_code: $postal_code
@@ -412,6 +442,7 @@ class RealtorScraper(Scraper):
                                     limit: 200
                                     offset: $offset
                                 ) %s""" % (
+                is_foreclosure,
                 listing_type.value.lower(),
                 date_param,
                 pending_or_contingent_param,
@@ -483,7 +514,7 @@ class RealtorScraper(Scraper):
                 mls_id=result["source"].get("listing_id")
                 if "source" in result and isinstance(result["source"], dict)
                 else None,
-                property_url=f"{self.PROPERTY_URL}{result['property_id']}",
+                property_url=f"{self.PROPERTY_URL}{result['property_id']}" if self.listing_type != ListingType.FOR_RENT else f"{self.PROPERTY_URL}M{result['property_id']}?listing_status=rental",
                 status="PENDING" if is_pending else result["status"].upper(),
                 list_price=result["list_price"],
                 list_date=result["list_date"].split("T")[0]
@@ -521,7 +552,7 @@ class RealtorScraper(Scraper):
         search_variables = {
             "offset": 0,
         }
-
+     
         search_type = (
             "comps"
             if self.radius and location_type == "address"
@@ -553,6 +584,11 @@ class RealtorScraper(Scraper):
                     "radius": "{}mi".format(self.radius),
                 }
 
+        elif location_type == "postal_code":
+            search_variables |= {
+                "postal_code": location_info.get("postal_code"),
+            }
+
         else:  #: general search, location
             search_variables |= {
                 "city": location_info.get("city"),
@@ -561,6 +597,9 @@ class RealtorScraper(Scraper):
                 "postal_code": location_info.get("postal_code"),
             }
 
+        if self.foreclosure: 
+            search_variables['foreclosure'] = self.foreclosure
+
         result = self.general_search(search_variables, search_type=search_type)
         total = result["total"]
         homes = result["properties"]
@@ -621,6 +660,7 @@ class RealtorScraper(Scraper):
 
     @staticmethod
     def _parse_description(result: dict) -> Description:
+
         description_data = result.get("description", {})
 
         if description_data is None or not isinstance(description_data, dict):
@@ -630,7 +670,16 @@ class RealtorScraper(Scraper):
         if style is not None:
             style = style.upper()
 
+        primary_photo = ""
+        if result and "primary_photo" in result:
+            primary_photo_info = result["primary_photo"]
+            if primary_photo_info and "href" in primary_photo_info:
+                primary_photo_href = primary_photo_info["href"]
+                primary_photo = primary_photo_href.replace("s.jpg", "od-w480_h360_x2.webp?w=1080&q=75")
+
         return Description(
+            primary_photo=primary_photo,
+            alt_photos=RealtorScraper.process_alt_photos(result.get("photos")),
             style=style,
             beds=description_data.get("beds"),
             baths_full=description_data.get("baths_full"),
@@ -643,6 +692,7 @@ class RealtorScraper(Scraper):
             stories=description_data.get("stories"),
         )
 
+
     @staticmethod
     def calculate_days_on_mls(result: dict) -> Optional[int]:
         list_date_str = result.get("list_date")
@@ -661,3 +711,16 @@ class RealtorScraper(Scraper):
                 days = (today - list_date).days
                 if days >= 0:
                     return days
+
+    @staticmethod
+    def process_alt_photos(photos_info):
+        try:
+            alt_photos = []
+            if photos_info:
+                for photo_info in photos_info:
+                    href = photo_info.get("href", "")
+                    alt_photo_href = href.replace("s.jpg", "od-w480_h360_x2.webp?w=1080&q=75")
+                    alt_photos.append(alt_photo_href)
+            return alt_photos
+        except Exception:
+            pass

homeharvest/utils.py

@@ -31,6 +31,8 @@ ordered_properties = [
     "stories",
     "hoa_fee",
     "parking_garage",
+    "primary_photo",
+    "alt_photos",
 ]
 
 
@@ -49,6 +51,8 @@ def process_result(result: Property) -> pd.DataFrame:
     prop_data["price_per_sqft"] = prop_data["prc_sqft"]
 
     description = result.description
+    prop_data["primary_photo"] = description.primary_photo
+    prop_data["alt_photos"] = ", ".join(description.alt_photos)
     prop_data["style"] = description.style
     prop_data["beds"] = description.beds
     prop_data["full_baths"] = description.baths_full

pyproject.toml

@@ -1,8 +1,8 @@
 [tool.poetry]
 name = "homeharvest"
-version = "0.3.9"
+version = "0.3.12"
-description = "Real estate scraping library supporting Zillow, Realtor.com & Redfin."
+description = "Real estate scraping library"
-authors = ["Zachary Hampton <zachary@zacharysproducts.com>", "Cullen Watson <cullen@cullen.ai>"]
+authors = ["Zachary Hampton <zachary@bunsly.com>", "Cullen Watson <cullen@bunsly.com>"]
 homepage = "https://github.com/Bunsly/HomeHarvest"
 readme = "README.md"
 
@@ -13,7 +13,6 @@ homeharvest = "homeharvest.cli:main"
 python = ">=3.10,<3.13"
 requests = "^2.31.0"
 pandas = "^2.1.1"
-openpyxl = "^3.1.2"
 
 
 [tool.poetry.group.dev.dependencies]

tests/test_realtor.py

@@ -139,3 +139,15 @@ def test_realtor_bad_address():
     if len(bad_results) == 0:
         assert True
 
+
+def test_realtor_foreclosed():
+    foreclosed = scrape_property(
+        location="Dallas, TX", listing_type="for_sale", past_days=100, foreclosure=True
+    )
+
+    not_foreclosed = scrape_property(
+        location="Dallas, TX", listing_type="for_sale", past_days=100, foreclosure=False
+    )
+
+    assert len(foreclosed) != len(not_foreclosed)
+