Add availability parameter to search_listing() (#5)

Allow searching for sold listings by adding an availability parameter:
- "available" - active listings
- "negotiations" - under negotiation
- "sold" - sold/rented listings

Default remains ["available", "negotiations"] to match current behavior.

Example: f.search_listing('amsterdam', availability='sold')

Bump version to 2.4.0

Author: 0xMH

examples/search_sold.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Search for sold listings on Funda.
+
+Find recently sold properties in a given location to analyze
+market prices and trends.
+
+Usage:
+    uv run examples/search_sold.py amsterdam
+    uv run examples/search_sold.py rotterdam --max-price 500000
+    uv run examples/search_sold.py utrecht --pages 3
+"""
+
+import argparse
+
+from funda import Funda
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Search for sold listings")
+    parser.add_argument("location", help="City or area to search in")
+    parser.add_argument("--min-price", type=int, help="Minimum price")
+    parser.add_argument("--max-price", type=int, help="Maximum price")
+    parser.add_argument("--pages", type=int, default=1, help="Number of pages (15 results each)")
+    args = parser.parse_args()
+
+    with Funda() as f:
+        print(f"Searching for sold listings in {args.location}...")
+        print()
+
+        all_listings = []
+        for page in range(args.pages):
+            results = f.search_listing(
+                location=args.location,
+                availability="sold",
+                price_min=args.min_price,
+                price_max=args.max_price,
+                sort="newest",
+                page=page,
+            )
+            all_listings.extend(results)
+
+            if len(results) < 15:
+                break
+
+        if not all_listings:
+            print("No sold listings found.")
+            return
+
+        print(f"Found {len(all_listings)} sold listings:")
+        print("-" * 70)
+        print(f"{'Address':<35} {'City':<15} {'Price':>12} {'m²':>6}")
+        print("-" * 70)
+
+        total_price = 0
+        total_area = 0
+        count_with_area = 0
+
+        for listing in all_listings:
+            title = listing["title"][:34]
+            city = (listing["city"] or "")[:14]
+            price = listing["price"]
+            area = listing["living_area"]
+
+            price_str = f"€{price:,}" if price else "N/A"
+            area_str = str(area) if area else "-"
+
+            print(f"{title:<35} {city:<15} {price_str:>12} {area_str:>6}")
+
+            if price:
+                total_price += price
+            if area:
+                total_area += area
+                count_with_area += 1
+
+        print("-" * 70)
+
+        # Summary statistics
+        if all_listings:
+            avg_price = total_price // len(all_listings)
+            print(f"\nAverage sold price: €{avg_price:,}")
+
+            if count_with_area > 0:
+                avg_area = total_area // count_with_area
+                avg_price_m2 = total_price // total_area
+                print(f"Average living area: {avg_area} m²")
+                print(f"Average price per m²: €{avg_price_m2:,}")
+
+
+if __name__ == "__main__":
+    main()

funda/funda.py

@@ -315,6 +315,7 @@ def search_listing(
         self,
         location: str | list[str] | None = None,
         offering_type: str = "buy",
+        availability: str | list[str] | None = None,
         price_min: int | None = None,
         price_max: int | None = None,
         area_min: int | None = None,
@@ -332,6 +333,8 @@ def search_listing(
         Args:
             location: City/area name(s) or postcode to search in
             offering_type: "buy" or "rent"
+            availability: Filter by status - "available", "negotiations", "sold",
+                or a list combining them. Default: ["available", "negotiations"]
             price_min: Minimum price
             price_max: Maximum price
             area_min: Minimum living area in m²
@@ -350,6 +353,7 @@ def search_listing(
 
         Example:
             >>> f.search_listing('amsterdam', price_max=500000)
+            >>> f.search_listing('amsterdam', availability='sold')  # sold listings
             >>> f.search_listing('1012AB', radius_km=30, price_max=1250000, energy_label=['A', 'A+'])
         """
         import json
@@ -359,9 +363,19 @@ def search_listing(
         if location:
             locations = [location] if isinstance(location, str) else list(location)
 
+        # Normalize availability - map user-friendly "sold" to API's "unavailable"
+        if availability is None:
+            avail_list = ["available", "negotiations"]
+        elif isinstance(availability, str):
+            avail_list = [availability]
+        else:
+            avail_list = list(availability)
+        # Map "sold" to "unavailable" (API terminology)
+        avail_list = ["unavailable" if v == "sold" else v for v in avail_list]
+
         # Build search params
         params: dict[str, Any] = {
-            "availability": ["available", "negotiations"],
+            "availability": avail_list,
             "type": ["single"],
             "zoning": ["residential"],
             "object_type": object_type or ["house", "apartment"],

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyfunda"
-version = "2.3.0"
+version = "2.4.0"
 description = "Python API for Funda.nl real estate listings"
 readme = "README.md"
 license = "AGPL-3.0-or-later"