pyfunda 2.0.0__py3-none-any.whl

funda/__init__.py

@@ -0,0 +1,20 @@
+"""
+Funda - Python API for Funda.nl real estate listings.
+
+Example usage:
+    >>> from funda import Funda
+    >>> f = Funda()
+    >>> listing = f.get_listing(43117443)
+    >>> print(listing['title'], listing['price'])
+    Reehorst 13 695000
+
+    >>> results = f.search_listing('amsterdam', price_max=500000)
+    >>> for r in results[:3]:
+    ...     print(r['title'], r['city'])
+"""
+
+from funda.funda import Funda, FundaAPI
+from funda.listing import Listing
+
+__version__ = "2.0.0"
+__all__ = ["Funda", "FundaAPI", "Listing"]

funda/funda.py

@@ -0,0 +1,463 @@
+"""Main Funda API class."""
+
+import re
+from typing import Any
+
+import requests
+
+from funda.listing import Listing
+
+
+# API endpoints
+API_BASE = "https://listing-detail-page.funda.io/api/v4/listing/object/nl"
+API_LISTING = f"{API_BASE}/{{listing_id}}"
+API_LISTING_TINY = f"{API_BASE}/tinyId/{{tiny_id}}"
+API_SEARCH = "https://listing-search-wonen.funda.io/_msearch/template"
+
+# Headers for mobile API
+HEADERS = {
+    "user-agent": "Dart/3.9 (dart:io)",
+    "x-funda-app-platform": "android",
+    "content-type": "application/json",
+}
+
+SEARCH_HEADERS = {
+    "user-agent": "Dart/3.9 (dart:io)",
+    "content-type": "application/x-ndjson",
+    "referer": "https://www.funda.nl/",
+}
+
+
+def _parse_area(value: str | None) -> int | None:
+    """Parse area string like '200 m²' or '2.960 m²' to integer."""
+    if not value:  # handles None and ''
+        return None
+    if isinstance(value, (int, float)):
+        return int(value)
+    # Remove ' m²' suffix and '.' thousand separator (Dutch locale)
+    cleaned = value.replace(' m²', '').replace('.', '')
+    return int(cleaned) if cleaned.isdigit() else None
+
+
+class Funda:
+    """Main interface to Funda API.
+
+    Example:
+        >>> from funda import Funda
+        >>> f = Funda()
+        >>> listing = f.get_listing(43117443)
+        >>> print(listing['title'], listing['city'])
+        Reehorst 13 Luttenberg
+        >>> results = f.search_listing('amsterdam', price_max=500000)
+        >>> for r in results[:3]:
+        ...     print(r['title'], r['price'])
+    """
+
+    TINYID_PATTERN = re.compile(r"/(\d{7,9})/?(?:\?|$|#)")
+
+    def __init__(self, timeout: int = 30):
+        """Initialize Funda API client.
+
+        Args:
+            timeout: Request timeout in seconds
+        """
+        self.timeout = timeout
+        self._session: requests.Session | None = None
+
+    @property
+    def session(self) -> requests.Session:
+        """Lazily create HTTP session."""
+        if self._session is None:
+            self._session = requests.Session()
+            self._session.headers.update(HEADERS)
+        return self._session
+
+    def close(self) -> None:
+        """Close the HTTP session."""
+        if self._session:
+            self._session.close()
+            self._session = None
+
+    def __enter__(self) -> "Funda":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    # -------------------------------------------------------------------------
+    # Listing methods
+    # -------------------------------------------------------------------------
+
+    def get_listing(self, listing_id: int | str) -> Listing:
+        """Get a listing by ID or URL.
+
+        Args:
+            listing_id: Numeric ID (globalId or tinyId) or full URL
+
+        Returns:
+            Listing object with property data
+
+        Example:
+            >>> f.get_listing(43117443)
+            >>> f.get_listing('https://www.funda.nl/detail/koop/city/house-123/43117443/')
+        """
+        # If it's a URL, extract tinyId
+        if isinstance(listing_id, str) and 'funda.nl' in listing_id:
+            match = self.TINYID_PATTERN.search(listing_id)
+            if not match:
+                raise ValueError(f"Could not extract listing ID from URL: {listing_id}")
+            listing_id = match.group(1)
+
+        # Try tinyId endpoint first (8-9 digits), then globalId (7 digits)
+        listing_id_str = str(listing_id)
+        if len(listing_id_str) >= 8:
+            url = API_LISTING_TINY.format(tiny_id=listing_id_str)
+        else:
+            url = API_LISTING.format(listing_id=listing_id_str)
+
+        response = self.session.get(url, timeout=self.timeout)
+
+        # If tinyId fails, try as globalId
+        if response.status_code == 404 and len(listing_id_str) >= 8:
+            url = API_LISTING.format(listing_id=listing_id_str)
+            response = self.session.get(url, timeout=self.timeout)
+
+        if response.status_code != 200:
+            raise LookupError(f"Listing {listing_id} not found")
+
+        data = response.json()
+        return self._parse_listing(data)
+
+    def search_listing(
+        self,
+        location: str | list[str] | None = None,
+        offering_type: str = "buy",
+        price_min: int | None = None,
+        price_max: int | None = None,
+        area_min: int | None = None,
+        area_max: int | None = None,
+        plot_min: int | None = None,
+        plot_max: int | None = None,
+        object_type: list[str] | None = None,
+        energy_label: list[str] | None = None,
+        radius_km: int | None = None,
+        sort: str | None = None,
+        page: int = 0,
+    ) -> list[Listing]:
+        """Search for listings.
+
+        Args:
+            location: City/area name(s) or postcode to search in
+            offering_type: "buy" or "rent"
+            price_min: Minimum price
+            price_max: Maximum price
+            area_min: Minimum living area in m²
+            area_max: Maximum living area in m²
+            plot_min: Minimum plot area in m²
+            plot_max: Maximum plot area in m²
+            object_type: Property types (e.g. ["house", "apartment"])
+            energy_label: Energy labels (e.g. ["A", "A+", "A++"])
+            radius_km: Search radius in km (use with single location/postcode)
+            sort: Sort order - "newest", "oldest", "price_asc", "price_desc",
+                  "area_asc", "area_desc", "plot_desc", "city", "postcode", or None
+            page: Page number (0-indexed, 15 results per page)
+
+        Returns:
+            List of Listing objects (max 15 per page)
+
+        Example:
+            >>> f.search_listing('amsterdam', price_max=500000)
+            >>> f.search_listing('1012AB', radius_km=30, price_max=1250000, energy_label=['A', 'A+'])
+        """
+        import json
+
+        # Normalize location to list
+        locations = None
+        if location:
+            locations = [location] if isinstance(location, str) else list(location)
+
+        # Build search params
+        params: dict[str, Any] = {
+            "availability": ["available", "negotiations"],
+            "type": ["single"],
+            "zoning": ["residential"],
+            "object_type": object_type or ["house", "apartment"],
+            "publication_date": {"no_preference": True},
+            "offering_type": offering_type,
+            "page": {"from": page * 15},
+        }
+
+        # Sort
+        sort_map = {
+            "newest": ("publish_date_utc", "desc"),
+            "oldest": ("publish_date_utc", "asc"),
+            "price_asc": ("price.selling_price", "asc"),
+            "price_desc": ("price.selling_price", "desc"),
+            "area_asc": ("floor_area", "asc"),
+            "area_desc": ("floor_area", "desc"),
+            "plot_desc": ("plot_area", "desc"),
+            "city": ("address.city", "asc"),
+            "postcode": ("address.postal_code", "asc"),
+        }
+        if sort and sort in sort_map:
+            field, order = sort_map[sort]
+            params["sort"] = {"field": field, "order": order}
+        else:
+            params["sort"] = {"field": None, "order": None}
+
+        # Location - either radius search or selected_area
+        if locations and radius_km and len(locations) == 1:
+            # Radius search from postcode or city
+            # Valid radius values in the geo index
+            valid_radii = [1, 2, 5, 10, 15, 30, 50]
+            actual_radius = min(valid_radii, key=lambda x: abs(x - radius_km))
+            loc_id = locations[0].lower().replace(" ", "-") + "-0"
+            params["radius_search"] = {
+                "index": "geo-wonen-alias-prod",
+                "id": loc_id,
+                "path": f"area_with_radius.{actual_radius}",
+            }
+        elif locations:
+            params["selected_area"] = locations
+
+        # Price filter - format depends on offering type
+        if price_min is not None or price_max is not None:
+            price_key = "selling_price" if offering_type == "buy" else "rent_price"
+            price_filter: dict[str, Any] = {}
+            if price_min:
+                price_filter["from"] = price_min
+            if price_max:
+                price_filter["to"] = price_max
+            params["price"] = {price_key: price_filter}
+
+        # Living area filter
+        if area_min is not None or area_max is not None:
+            floor_filter: dict[str, Any] = {}
+            if area_min:
+                floor_filter["from"] = area_min
+            if area_max:
+                floor_filter["to"] = area_max
+            params["floor_area"] = floor_filter
+
+        # Plot area filter
+        if plot_min is not None or plot_max is not None:
+            plot_filter: dict[str, Any] = {}
+            if plot_min:
+                plot_filter["from"] = plot_min
+            if plot_max:
+                plot_filter["to"] = plot_max
+            params["plot_area"] = plot_filter
+
+        # Energy label filter
+        if energy_label:
+            params["energy_label"] = energy_label
+
+        # Build NDJSON query
+        index_line = json.dumps({"index": "listings-wonen-searcher-alias-prod"})
+        query_line = json.dumps({"id": "search_result_20250805", "params": params})
+        query = f"{index_line}\n{query_line}\n"
+
+        response = requests.post(
+            API_SEARCH,
+            headers=SEARCH_HEADERS,
+            data=query,
+            timeout=self.timeout,
+        )
+
+        if response.status_code != 200:
+            raise RuntimeError(f"Search failed (status {response.status_code})")
+
+        data = response.json()
+        return self._parse_search_results(data)
+
+    # -------------------------------------------------------------------------
+    # Parsing methods
+    # -------------------------------------------------------------------------
+
+    def _parse_listing(self, data: dict) -> Listing:
+        """Parse API response into Listing object."""
+        identifiers = data.get("Identifiers", {})
+        address = data.get("AddressDetails", {})
+        price_data = data.get("Price", {})
+        coords = data.get("Coordinates", {})
+        media = data.get("Media", {})
+        fast_view = data.get("FastView", {})
+        ads = data.get("Advertising", {}).get("TargetingOptions", {})
+
+        # Build listing data
+        listing_data = {
+            "global_id": identifiers.get("GlobalId"),
+            "tiny_id": identifiers.get("TinyId"),
+            "title": address.get("Title"),
+            "city": address.get("City"),
+            "postcode": address.get("PostCode"),
+            "province": address.get("Province"),
+            "neighbourhood": address.get("NeighborhoodName"),
+            "house_number": address.get("HouseNumber"),
+            "house_number_ext": address.get("HouseNumberExtension"),
+            "municipality": ads.get("gemeente"),
+            "price": price_data.get("NumericSellingPrice") or price_data.get("NumericRentalPrice"),
+            "price_formatted": price_data.get("SellingPrice") or price_data.get("RentalPrice"),
+            "offering_type": data.get("OfferingType"),
+            "object_type": data.get("ObjectType"),
+            "construction_type": data.get("ConstructionType"),
+            "status": "sold" if data.get("IsSoldOrRented") else "available",
+            "energy_label": fast_view.get("EnergyLabel"),
+            "living_area": int(ads["woonoppervlakte"]) if ads.get("woonoppervlakte", "").isdigit() else _parse_area(fast_view.get("LivingArea")),
+            "living_area_formatted": fast_view.get("LivingArea"),
+            "plot_area": int(ads["perceeloppervlakte"]) if ads.get("perceeloppervlakte", "").isdigit() else _parse_area(fast_view.get("PlotArea")),
+            "plot_area_formatted": fast_view.get("PlotArea"),
+            "bedrooms": fast_view.get("NumberOfBedrooms"),
+            "rooms": int(ads["aantalkamers"]) if ads.get("aantalkamers") else None,
+            "construction_year": int(ads["bouwjaar"]) if ads.get("bouwjaar") and ads["bouwjaar"].isdigit() else None,
+            "description": data.get("ListingDescription", {}).get("Description"),
+            "highlight": data.get("Promo", {}).get("Blikvanger", {}).get("Text"),
+            "publication_date": data.get("PublicationDate"),
+            # Booleans
+            "has_garden": ads.get("tuin") == "true",
+            "has_balcony": ads.get("balkon") == "true",
+            "has_solar_panels": ads.get("zonnepanelen") == "true",
+            "has_heat_pump": ads.get("warmtepomp") == "true",
+            "has_roof_terrace": ads.get("dakterras") == "true",
+            "has_parking_on_site": ads.get("parkeergelegenheidopeigenterrein") == "true",
+            "has_parking_enclosed": ads.get("parkeergelegenheidopafgeslotenterrein") == "true",
+            "open_house": ads.get("openhuis") == "true",
+            "is_auction": price_data.get("IsAuction", False),
+            "is_energy_efficient": ads.get("energiezuinig") == "true",
+            "is_monument": ads.get("monumentalestatus") == "true",
+            "is_fixer_upper": ads.get("kluswoning") == "true",
+            "house_type": ads.get("soortwoning"),
+            # URLs
+            "google_maps_url": data.get("GoogleMapsObjectUrl"),
+            "share_url": data.get("Share", {}).get("Url"),
+            "brochure_url": media.get("Brochure", {}).get("CdnUrl"),
+        }
+
+        # Coordinates
+        if coords.get("Latitude") and coords.get("Longitude"):
+            listing_data["latitude"] = float(coords["Latitude"])
+            listing_data["longitude"] = float(coords["Longitude"])
+            listing_data["coordinates"] = (listing_data["latitude"], listing_data["longitude"])
+
+        # Photos - IDs and full URLs
+        photos_data = media.get("Photos", {})
+        photo_base = photos_data.get("MediaBaseUrl", "").replace("{id}", "{}")
+        photo_items = photos_data.get("Items", [])
+        listing_data["photos"] = [p.get("Id") for p in photo_items if p.get("Id")]
+        listing_data["photo_urls"] = [photo_base.format(p["Id"]) for p in photo_items if p.get("Id")] if photo_base else []
+        listing_data["photo_count"] = len(listing_data["photos"])
+
+        # Floorplans
+        floorplans_data = media.get("LegacyFloorPlan", {})
+        floorplan_base = floorplans_data.get("ThumbnailBaseUrl", "").replace("{id}", "{}")
+        floorplan_items = floorplans_data.get("Items", [])
+        listing_data["floorplans"] = [f.get("Id") for f in floorplan_items if f.get("Id")]
+        listing_data["floorplan_urls"] = [
+            floorplan_base.format(f["ThumbnailId"])
+            for f in floorplan_items if f.get("ThumbnailId")
+        ] if floorplan_base else []
+
+        # Videos
+        videos_data = media.get("Videos", {})
+        video_base = videos_data.get("MediaBaseUrl", "").replace("{id}", "{}")
+        video_items = videos_data.get("Items", [])
+        listing_data["videos"] = [v.get("Id") for v in video_items if v.get("Id")]
+        listing_data["video_urls"] = [video_base.format(v["Id"]) for v in video_items if v.get("Id")] if video_base else []
+
+        # 360 Photos
+        photos360_data = media.get("LegacyPhotos360", {})
+        photos360_base = photos360_data.get("ThumbnailBaseUrl", "").replace("{id}", "{}")
+        photos360_items = photos360_data.get("Items", [])
+        listing_data["photos_360"] = [
+            {"name": p.get("DisplayName"), "id": p.get("Id"), "url": photos360_base.format(p["Id"]) if photos360_base else None}
+            for p in photos360_items if p.get("Id")
+        ]
+
+        # URL
+        city_slug = address.get("City", "").lower().replace(" ", "-")
+        title_slug = address.get("Title", "").lower().replace(" ", "-")
+        tiny_id = identifiers.get("TinyId")
+        offering = "koop" if data.get("OfferingType") == "Sale" else "huur"
+        listing_data["url"] = f"https://www.funda.nl/detail/{offering}/{city_slug}/{title_slug}/{tiny_id}/"
+
+        # Characteristics
+        characteristics = {}
+        for section in data.get("KenmerkSections", []):
+            for item in section.get("KenmerkenList", []):
+                if item.get("Label") and item.get("Value"):
+                    characteristics[item["Label"]] = item["Value"]
+        listing_data["characteristics"] = characteristics
+
+        # Extract specific fields from characteristics
+        listing_data["offered_since"] = characteristics.get("Aangeboden sinds")
+        listing_data["acceptance"] = characteristics.get("Aanvaarding")
+        listing_data["price_per_m2"] = characteristics.get("Vraagprijs per m²")
+
+        # Broker
+        tracking = data.get("Tracking", {}).get("Values", {})
+        brokers = tracking.get("brokers", [])
+        if brokers:
+            listing_data["broker_id"] = brokers[0].get("broker_id")
+            listing_data["broker_association"] = brokers[0].get("broker_association")
+
+        # Insights
+        insights = data.get("ObjectInsights", {})
+        if insights:
+            listing_data["views"] = insights.get("Views")
+            listing_data["saves"] = insights.get("Saves")
+
+        return Listing(
+            listing_id=identifiers.get("TinyId") or identifiers.get("GlobalId"),
+            data=listing_data
+        )
+
+    def _parse_search_results(self, data: dict) -> list[Listing]:
+        """Parse search API response into list of Listings."""
+        listings = []
+        responses = data.get("responses", [])
+
+        if not responses:
+            return listings
+
+        hits = responses[0].get("hits", {}).get("hits", [])
+
+        for hit in hits:
+            source = hit.get("_source", {})
+            address = source.get("address", {})
+
+            # Price
+            price_data = source.get("price", {})
+            if isinstance(price_data, dict):
+                price = price_data.get("selling_price", [None])[0]
+                if not price:
+                    price = price_data.get("rent_price", [None])[0] if price_data.get("rent_price") else None
+            else:
+                price = price_data
+
+            listing_data = {
+                "global_id": int(hit.get("_id", 0)),
+                "title": f"{address.get('street_name', '')} {address.get('house_number', '')}".strip(),
+                "city": address.get("city"),
+                "postcode": address.get("postal_code"),
+                "province": address.get("province"),
+                "neighbourhood": address.get("neighbourhood"),
+                "price": price,
+                "living_area": source.get("floor_area", [None])[0] if source.get("floor_area") else None,
+                "plot_area": source.get("plot_area_range", {}).get("gte"),
+                "bedrooms": source.get("number_of_bedrooms"),
+                "energy_label": source.get("energy_label"),
+                "object_type": source.get("object_type"),
+                "construction_type": source.get("construction_type"),
+                "photos": source.get("thumbnail_id", [])[:5],
+            }
+
+            listings.append(Listing(
+                listing_id=hit.get("_id"),
+                data=listing_data
+            ))
+
+        return listings
+
+
+# Convenience alias
+FundaAPI = Funda

funda/listing.py

@@ -0,0 +1,138 @@
+"""Listing class - represents a Funda property listing."""
+
+from typing import Any
+
+
+class Listing:
+    """A Funda property listing.
+
+    Data can be accessed as listing['key'] or listing.get('key').
+
+    Example:
+        >>> listing = funda.get_listing(43117443)
+        >>> listing['title']
+        'Reehorst 13'
+        >>> listing['price']
+        695000
+        >>> listing['city']
+        'Luttenberg'
+    """
+
+    default_info = ('main',)
+
+    keys_alias = {
+        'name': 'title',
+        'address': 'title',
+        'location': 'city',
+        'locality': 'city',
+        'area': 'living_area',
+        'size': 'living_area',
+        'coords': 'coordinates',
+        'lat': 'latitude',
+        'lng': 'longitude',
+        'lon': 'longitude',
+        'zip': 'postcode',
+        'zipcode': 'postcode',
+        'postal_code': 'postcode',
+        'type': 'object_type',
+        'property_type': 'object_type',
+        'images': 'photos',
+        'pictures': 'photos',
+        'media': 'photos',
+        'desc': 'description',
+        'text': 'description',
+        'agent': 'broker',
+        'realtor': 'broker',
+        'makelaar': 'broker',
+    }
+
+    def __init__(self, listing_id: str | int | None = None, data: dict | None = None):
+        self.listing_id = str(listing_id) if listing_id else None
+        self.data: dict[str, Any] = data or {}
+        self.current_info: list[str] = []
+
+    def __repr__(self) -> str:
+        title = self.data.get('title', 'Unknown')
+        city = self.data.get('city', '')
+        return f"<Listing id:{self.listing_id} [{title}, {city}]>"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __contains__(self, key: str) -> bool:
+        return self._normalize_key(key) in self.data
+
+    def __getitem__(self, key: str) -> Any:
+        normalized = self._normalize_key(key)
+        if normalized not in self.data:
+            raise KeyError(key)
+        return self.data[normalized]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.data[self._normalize_key(key)] = value
+
+    def __bool__(self) -> bool:
+        return bool(self.listing_id or self.data.get('title'))
+
+    def _normalize_key(self, key: str) -> str:
+        """Normalize key using aliases."""
+        key = key.lower().replace('-', '_').replace(' ', '_')
+        return self.keys_alias.get(key, key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value with optional default."""
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+    def keys(self) -> list[str]:
+        """Return all available keys."""
+        return list(self.data.keys())
+
+    def items(self) -> list[tuple[str, Any]]:
+        """Return all key-value pairs."""
+        return list(self.data.items())
+
+    def values(self) -> list[Any]:
+        """Return all values."""
+        return list(self.data.values())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return data as a plain dictionary."""
+        return self.data.copy()
+
+    def summary(self) -> str:
+        """Return a text summary of the listing."""
+        lines = []
+        title = self.data.get('title', 'Unknown')
+        city = self.data.get('city', '')
+        lines.append(f"Listing: {title}, {city}")
+
+        if price := self.data.get('price_formatted'):
+            lines.append(f"Price: {price}")
+        elif price := self.data.get('price'):
+            lines.append(f"Price: €{price:,}")
+
+        if area := self.data.get('living_area'):
+            lines.append(f"Living area: {area}")
+
+        if bedrooms := self.data.get('bedrooms'):
+            lines.append(f"Bedrooms: {bedrooms}")
+
+        if energy := self.data.get('energy_label'):
+            lines.append(f"Energy label: {energy}")
+
+        if url := self.data.get('url'):
+            lines.append(f"URL: {url}")
+
+        return '\n'.join(lines)
+
+    def getID(self) -> str | None:
+        """Return the listing ID."""
+        return self.listing_id
+
+    @property
+    def id(self) -> str | None:
+        """Alias for listing_id."""
+        return self.listing_id

pyfunda-2.0.0.dist-info/METADATA

@@ -0,0 +1,445 @@
+Metadata-Version: 2.4
+Name: pyfunda
+Version: 2.0.0
+Summary: Python API for Funda.nl real estate listings
+Project-URL: Homepage, https://github.com/0xMH/pyfunda
+Project-URL: Repository, https://github.com/0xMH/pyfunda
+Project-URL: Issues, https://github.com/0xMH/pyfunda/issues
+Author: 0xMH
+License-Expression: MIT
+Keywords: api,funda,housing,netherlands,real-estate,scraper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28.0
+Description-Content-Type: text/markdown
+
+# Funda
+
+Python API for [Funda.nl](https://www.funda.nl) real estate listings.
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## Quick Start
+
+```python
+from funda import Funda
+
+f = Funda()
+
+# Get a listing by ID
+listing = f.get_listing(43117443)
+print(listing['title'], listing['city'])
+# Reehorst 13 Luttenberg
+
+# Get a listing by URL
+listing = f.get_listing('https://www.funda.nl/detail/koop/amsterdam/appartement-123/43117443/')
+
+# Search listings
+results = f.search_listing('amsterdam', price_max=500000)
+for r in results:
+    print(r['title'], r['price'])
+```
+
+## How It Works
+
+This library uses Funda's undocumented mobile app API, which provides clean JSON responses unlike the website that embeds data in Nuxt.js/JavaScript bundles.
+
+### Discovery Process
+
+The API was reverse engineered by intercepting and analyzing HTTPS traffic from the official Funda Android app:
+
+1. Configured an Android device to route traffic through an intercepting proxy
+2. Used the Funda app normally - browsing listings, searching, opening shared URLs
+3. Identified the `*.funda.io` API infrastructure separate from the `www.funda.nl` website
+4. Analyzed request/response patterns to understand the query format and available filters
+5. Discovered how the app resolves URL-based IDs (`tinyId`) to internal IDs (`globalId`)
+
+### API Architecture
+
+The mobile app communicates with a separate API at `*.funda.io`:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `listing-detail-page.funda.io/api/v4/listing/object/nl/{globalId}` | GET | Fetch listing by internal ID |
+| `listing-detail-page.funda.io/api/v4/listing/object/nl/tinyId/{tinyId}` | GET | Fetch listing by URL ID |
+| `listing-search-wonen.funda.io/_msearch/template` | POST | Search listings |
+
+### ID System
+
+Funda uses two ID systems:
+- **globalId**: Internal numeric ID (7 digits), used in the database
+- **tinyId**: Public-facing ID (8-9 digits), appears in URLs like `funda.nl/detail/koop/amsterdam/.../{tinyId}/`
+
+The `tinyId` endpoint was key - it allows fetching any listing directly from a Funda URL without needing to know the internal ID.
+
+### Search API
+
+Search uses Elasticsearch's [Multi Search Template API](https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-search-template.html) with NDJSON format:
+
+```
+{"index":"listings-wonen-searcher-alias-prod"}
+{"id":"search_result_20250805","params":{...}}
+```
+
+**Search parameters:**
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `selected_area` | Location filter | `["amsterdam"]` |
+| `radius_search` | Radius from location | `{"index": "geo-wonen-alias-prod", "id": "1012AB-0", "path": "area_with_radius.10"}` |
+| `offering_type` | Buy or rent | `"buy"` or `"rent"` |
+| `price.selling_price` | Price range (buy) | `{"from": 200000, "to": 500000}` |
+| `price.rent_price` | Price range (rent) | `{"from": 500, "to": 2000}` |
+| `object_type` | Property types | `["house", "apartment"]` |
+| `floor_area` | Living area m² | `{"from": 50, "to": 150}` |
+| `plot_area` | Plot area m² | `{"from": 100, "to": 500}` |
+| `energy_label` | Energy labels | `["A", "A+", "A++"]` |
+| `sort` | Sort order | `{"field": "publish_date_utc", "order": "desc"}` |
+| `page.from` | Pagination offset | `0`, `15`, `30`... |
+
+Results are paginated with 15 listings per page.
+
+**Valid radius values:** 1, 2, 5, 10, 15, 30, 50 km (other values are not indexed).
+
+### Required Headers
+
+```
+User-Agent: Dart/3.9 (dart:io)
+X-Funda-App-Platform: android
+Content-Type: application/json
+```
+
+### Response Data
+
+Listing responses include:
+- **Identifiers** - globalId, tinyId
+- **AddressDetails** - title, city, postcode, province, neighbourhood, house number
+- **Price** - numeric and formatted prices (selling or rental), auction flag
+- **FastView** - bedrooms, living area, plot area, energy label
+- **Media** - photos, floorplans, videos, 360° photos, brochure URL (all with CDN base URLs)
+- **KenmerkSections** - detailed property characteristics (70+ fields)
+- **Coordinates** - latitude/longitude
+- **ObjectInsights** - view and save counts
+- **Advertising.TargetingOptions** - boolean features (garden, balcony, solar panels, heat pump, parking, etc.), construction year, room counts
+- **Share** - shareable URL
+- **GoogleMapsObjectUrl** - direct Google Maps link
+- **PublicationDate** - when the listing was published
+- **Tracking.Values.brokers** - broker ID and association
+
+## API Reference
+
+### Funda
+
+Main entry point for the API.
+
+```python
+from funda import Funda
+
+f = Funda(timeout=30)
+```
+
+#### get_listing(listing_id)
+
+Get a single listing by ID or URL.
+
+```python
+# By numeric ID (tinyId or globalId)
+listing = f.get_listing(43117443)
+
+# By URL
+listing = f.get_listing('https://www.funda.nl/detail/koop/city/house-name/43117443/')
+```
+
+#### search_listing(location, ...)
+
+Search for listings with filters.
+
+```python
+results = f.search_listing(
+    location='amsterdam',           # City or area name
+    offering_type='buy',            # 'buy' or 'rent'
+    price_min=200000,               # Minimum price
+    price_max=500000,               # Maximum price
+    area_min=50,                    # Minimum living area (m²)
+    area_max=150,                   # Maximum living area (m²)
+    plot_min=100,                   # Minimum plot area (m²)
+    plot_max=500,                   # Maximum plot area (m²)
+    object_type=['house'],          # Property types (default: house, apartment)
+    energy_label=['A', 'A+'],       # Energy labels to filter
+    sort='newest',                  # Sort order (see below)
+    page=0,                         # Page number (15 results per page)
+)
+```
+
+**Radius search** - search within a radius from a postcode or city:
+
+```python
+results = f.search_listing(
+    location='1012AB',              # Postcode or city
+    radius_km=10,                   # Search radius in km
+    price_max=750000,
+)
+```
+
+> **Note:** Valid radius values are 1, 2, 5, 10, 15, 30, and 50 km. Other values are automatically mapped to the nearest valid radius.
+
+**Sort options:**
+
+| Sort Value | Description |
+|------------|-------------|
+| `newest` | Most recently published first |
+| `oldest` | Oldest listings first |
+| `price_asc` | Lowest price first |
+| `price_desc` | Highest price first |
+| `area_asc` | Smallest living area first |
+| `area_desc` | Largest living area first |
+| `plot_desc` | Largest plot area first |
+| `city` | Alphabetically by city |
+| `postcode` | Alphabetically by postcode |
+
+**Multiple locations:**
+
+```python
+results = f.search_listing(['amsterdam', 'rotterdam', 'utrecht'])
+```
+
+### Listing
+
+Listing objects support dict-like access with convenient aliases.
+
+**Basic info:**
+
+```python
+listing['title']            # Property title/address
+listing['city']             # City name
+listing['postcode']         # Postal code
+listing['province']         # Province
+listing['neighbourhood']    # Neighbourhood name
+listing['municipality']     # Municipality (gemeente)
+listing['house_number']     # House number
+listing['house_number_ext'] # House number extension (e.g., "A", "II")
+```
+
+**Price & Status:**
+
+```python
+listing['price']            # Numeric price
+listing['price_formatted']  # Formatted price string (e.g., "€ 450.000 k.k.")
+listing['price_per_m2']     # Price per m² (from characteristics)
+listing['status']           # "available" or "sold"
+listing['offering_type']    # "Sale" or "Rent"
+```
+
+**Property details:**
+
+```python
+listing['object_type']      # House, Apartment, etc.
+listing['house_type']       # Type of house (e.g., "Tussenwoning")
+listing['construction_type'] # New or existing construction
+listing['construction_year'] # Year built
+listing['bedrooms']         # Number of bedrooms
+listing['rooms']            # Total number of rooms
+listing['living_area']      # Living area in m²
+listing['plot_area']        # Plot area in m²
+listing['energy_label']     # Energy label (A, B, C, etc.)
+listing['description']      # Full description text
+```
+
+**Dates:**
+
+```python
+listing['publication_date'] # When listed on Funda
+listing['offered_since']    # "Offered since" date (from characteristics)
+listing['acceptance']       # Acceptance terms (e.g., "In overleg")
+```
+
+**Location:**
+
+```python
+listing['coordinates']      # (lat, lng) tuple
+listing['latitude']         # Latitude
+listing['longitude']        # Longitude
+listing['google_maps_url']  # Direct Google Maps link
+```
+
+**Media:**
+
+```python
+listing['photos']           # List of photo IDs
+listing['photo_urls']       # List of full CDN URLs for photos
+listing['photo_count']      # Number of photos
+listing['floorplans']       # List of floorplan IDs
+listing['floorplan_urls']   # List of full CDN URLs for floorplans
+listing['videos']           # List of video IDs
+listing['video_urls']       # List of video URLs
+listing['photos_360']       # List of 360° photo dicts with name, id, url
+listing['brochure_url']     # PDF brochure URL (if available)
+```
+
+**Property features (booleans):**
+
+```python
+listing['has_garden']           # Has garden
+listing['has_balcony']          # Has balcony
+listing['has_roof_terrace']     # Has roof terrace
+listing['has_solar_panels']     # Has solar panels
+listing['has_heat_pump']        # Has heat pump
+listing['has_parking_on_site']  # Parking on property
+listing['has_parking_enclosed'] # Enclosed parking
+listing['is_energy_efficient']  # Energy efficient property
+listing['is_monument']          # Listed/protected building
+listing['is_fixer_upper']       # Fixer-upper (kluswoning)
+listing['is_auction']           # Sold via auction
+listing['open_house']           # Has open house scheduled
+```
+
+**Stats & metadata:**
+
+```python
+listing['views']            # Number of views on Funda
+listing['saves']            # Number of times saved
+listing['highlight']        # Highlight text (blikvanger)
+listing['global_id']        # Internal Funda ID
+listing['tiny_id']          # Public ID (used in URLs)
+listing['url']              # Full Funda URL
+listing['share_url']        # Shareable URL
+listing['broker_id']        # Broker ID
+listing['broker_association'] # Broker association (e.g., "NVM")
+listing['characteristics']  # Dict of all detailed characteristics
+```
+
+**Key aliases** - these all work:
+
+| Alias | Canonical Key |
+|-------|---------------|
+| `name`, `address` | `title` |
+| `location`, `locality` | `city` |
+| `area`, `size` | `living_area` |
+| `type`, `property_type` | `object_type` |
+| `images`, `pictures`, `media` | `photos` |
+| `agent`, `realtor`, `makelaar` | `broker` |
+| `zip`, `zipcode`, `postal_code` | `postcode` |
+
+#### Methods
+
+```python
+listing.summary()       # Text summary of the listing
+listing.to_dict()       # Convert to plain dictionary
+listing.keys()          # List available keys
+listing.get('key')      # Get with default (like dict.get)
+listing.getID()         # Get listing ID
+```
+
+## Examples
+
+### Find apartments in Amsterdam under €400k
+
+```python
+from funda import Funda
+
+f = Funda()
+results = f.search_listing('amsterdam', price_max=400000)
+
+for listing in results:
+    print(f"{listing['title']}")
+    print(f"  Price: €{listing['price']:,}")
+    print(f"  Area: {listing.get('living_area', 'N/A')}")
+    print(f"  Bedrooms: {listing.get('bedrooms', 'N/A')}")
+    print()
+```
+
+### Get detailed listing information
+
+```python
+from funda import Funda
+
+f = Funda()
+listing = f.get_listing(43117443)
+
+print(listing.summary())
+
+# Access all characteristics
+for key, value in listing['characteristics'].items():
+    print(f"{key}: {value}")
+```
+
+### Search rentals in multiple cities
+
+```python
+from funda import Funda
+
+f = Funda()
+results = f.search_listing(
+    location=['amsterdam', 'rotterdam', 'den-haag'],
+    offering_type='rent',
+    price_max=2000,
+)
+
+print(f"Found {len(results)} rentals")
+```
+
+### Find energy-efficient homes with a garden
+
+```python
+from funda import Funda
+
+f = Funda()
+listing = f.get_listing(43117443)
+
+# Check property features
+if listing['has_garden'] and listing.get('has_solar_panels'):
+    print("Energy efficient with garden!")
+
+if listing['is_energy_efficient']:
+    print(f"Energy label: {listing['energy_label']}")
+```
+
+### Download listing photos
+
+```python
+from funda import Funda
+import requests
+
+f = Funda()
+listing = f.get_listing(43117443)
+
+# Photo URLs are ready to use
+for i, url in enumerate(listing['photo_urls'][:5]):
+    response = requests.get(url)
+    with open(f"photo_{i}.jpg", "wb") as file:
+        file.write(response.content)
+
+# Also available: floorplan_urls, video_urls
+```
+
+### Search by radius from postcode
+
+```python
+from funda import Funda
+
+f = Funda()
+results = f.search_listing(
+    location='1012AB',
+    radius_km=15,
+    price_max=600000,
+    energy_label=['A', 'A+', 'A++'],
+    sort='newest',
+)
+
+for r in results:
+    print(f"{r['title']} - €{r['price']:,}")
+```
+
+## License
+
+MIT

pyfunda-2.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+funda/__init__.py,sha256=4_ylEwS5cHhfKbFLO_CgdlbGrJ8Vzv006fpKy31-0Ts,524
+funda/funda.py,sha256=mQjGIiIUbatEFWqfECuwooaKd4i2iqY0BTONqSyNSJY,19092
+funda/listing.py,sha256=UQxQJwodADJ59Jm2envUNb9EIxfyiJGTuo0hUuswg1k,4103
+pyfunda-2.0.0.dist-info/METADATA,sha256=hhnINyWZVlaLJ-s50dBSf9u6vp_AGKlpAKq_Jxg3MtE,13675
+pyfunda-2.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pyfunda-2.0.0.dist-info/RECORD,,

pyfunda-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any