pyfunda 2.6.2__tar.gz → 2.9.0__tar.gz

{pyfunda-2.6.2 → pyfunda-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfunda
-Version: 2.6.2
+Version: 2.9.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
@@ -307,6 +307,125 @@ for change in history:
 
 > **Note:** This fetches data from the Walter Living API. Only called when explicitly requested (lazy-loaded).
 
+#### get_contact_info(listing)
+
+Get the realtor/makelaar agency name and phone number for a listing. Accepts a `Listing`, a numeric id (globalId or tinyId), or a Funda URL.
+
+```python
+listing = f.get_listing(43333315)
+contact = f.get_contact_info(listing)
+
+print(contact['name'], contact['phone'])
+# Scheffer Makelaardij B.V. 020-2470322
+```
+
+**Returns:** A dict with the primary broker hoisted to the top level:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Agency display name |
+| `phone` | Agency phone number |
+| `broker_id` | Numeric office id |
+| `association` | Trade association code (e.g. `VN`) |
+| `is_contacting_enabled` | Whether the in-app contact form is enabled |
+| `listing_id` / `tiny_id` / `listing_status` | Listing meta |
+| `brokers` | Full list of brokers (for the rare multi-agency case) |
+
+Raises `LookupError` if the listing has no contact info exposed.
+
+#### get_contact_form(listing)
+
+Get the agency's contact-form availability (which weekdays and times-of-day they accept inquiries through the in-app form).
+
+```python
+form = f.get_contact_form(43333315)
+print(form['days'], form['times_of_day'])
+# ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'] ['Morning', 'Afternoon']
+```
+
+**Returns:** Dict with `office_id`, `office_name`, `days`, `times_of_day`, `is_contacting_enabled`, `is_viewing_planner_enabled`, plus the raw `offices` list.
+
+#### get_listing_summary(listing)
+
+Lightweight version of `get_listing` (no descriptions, photos, kenmerken). Faster and smaller, useful for batch enrichment.
+
+```python
+summary = f.get_listing_summary(7985628)
+print(summary['title'], summary['price'], summary['energy_label'])
+# Semarangstraat 13 650000 C
+```
+
+**Returns:** A `Listing` object with summary fields (`title`, `price`, `living_area`, `plot_area`, `bedrooms`, `energy_label`, `broker_name`, `url`, `thumbnail_url`, …).
+
+#### get_similar_listings(listing)
+
+Get globalIds of similar / recently-sold listings near a given listing. Returns IDs only; combine with `get_listing_summary` or `get_listing` to materialize them.
+
+```python
+sim = f.get_similar_listings(7988952)
+for gid in sim['recently_sold']:
+    print(f.get_listing_summary(gid)['title'])
+```
+
+**Returns:** Dict with `recently_listed` and `recently_sold`, each a list of integer globalIds.
+
+#### get_market_insights(city, neighbourhood)
+
+Neighbourhood demographics and average asking €/m² for a (city, neighbourhood) pair. Accepts a `Listing` directly to use its city/neighbourhood automatically.
+
+```python
+mi = f.get_market_insights('Amsterdam', 'Twiske-West')
+# {'city': 'Amsterdam', 'neighbourhood': 'Twiske-West',
+#  'inhabitants': 2510, 'families_with_children_pct': 43.96,
+#  'avg_asking_price_per_m2': 5975}
+
+# Or pass a Listing
+listing = f.get_listing(43333315)
+mi = f.get_market_insights(listing)
+```
+
+**Returns:** Dict with `city`, `neighbourhood`, `inhabitants`, `families_with_children_pct`, `avg_asking_price_per_m2`. Raises `LookupError` for unknown neighbourhoods (HTTP 204).
+
+#### get_broker_info(broker)
+
+Get the agency's profile page: phone, email, website, postal address, affiliation (NVM/VBO/…), description, certificates, languages, services. Accepts a numeric `broker_id` or a `Listing` (uses its `broker_id` automatically).
+
+```python
+info = f.get_broker_info(24716)
+print(info['name'], info['phone'], info['email'])
+# Simone Dijkman Makelaardij 075 7725155 info@simonedijkman.nl
+
+# Or chain from a listing
+listing = f.get_listing(43333315)
+info = f.get_broker_info(listing)
+```
+
+#### get_broker_listings(broker)
+
+Every listing the agency has handled, tagged by status. Useful for analyzing an agency's deal history (sold dates, prices, neighbourhoods).
+
+```python
+listings = f.get_broker_listings(24716)
+sold = [l for l in listings if l['status'] == 'sold']
+for_sale = [l for l in listings if l['status'] == 'for_sale']
+print(f"{len(sold)} sold, {len(for_sale)} active")
+```
+
+**Returns:** Flat list of dicts. Each entry has `status` (`sold`, `for_sale`, `purchased`), `listing_id`, `tiny_id`, `title`, `street`, `house_number`, `postcode`, `city`, `latitude`, `longitude`, `price`, `price_formatted`, `price_condition`, `publication_date`, `transaction_date`, `image_url`, `detail_url`.
+
+#### get_broker_reviews(broker)
+
+Customer reviews and aggregate scores per agency. The API returns only a representative sample of recent reviews — `number_of_reviews` is the true total.
+
+```python
+r = f.get_broker_reviews(24716)
+print(f"{r['average']}/10 over {r['number_of_reviews']} reviews")
+for review in r['reviews']:
+    print(review['date'], review['average'], review['text'][:60])
+```
+
+**Returns:** Dict with `average` (float), `number_of_reviews`, `selectivity_percentage`, a single `highlight` review, and a `reviews` list. Each review has subscores (`expertise`, `local_market_knowledge`, `price_and_quality`, `service_and_guidance`, `average`), `transaction_type`, `text`, and `date`.
+
 ### Listing
 
 Listing objects support dict-like access with convenient aliases.

{pyfunda-2.6.2 → pyfunda-2.9.0}/README.md

@@ -283,6 +283,125 @@ for change in history:
 
 > **Note:** This fetches data from the Walter Living API. Only called when explicitly requested (lazy-loaded).
 
+#### get_contact_info(listing)
+
+Get the realtor/makelaar agency name and phone number for a listing. Accepts a `Listing`, a numeric id (globalId or tinyId), or a Funda URL.
+
+```python
+listing = f.get_listing(43333315)
+contact = f.get_contact_info(listing)
+
+print(contact['name'], contact['phone'])
+# Scheffer Makelaardij B.V. 020-2470322
+```
+
+**Returns:** A dict with the primary broker hoisted to the top level:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Agency display name |
+| `phone` | Agency phone number |
+| `broker_id` | Numeric office id |
+| `association` | Trade association code (e.g. `VN`) |
+| `is_contacting_enabled` | Whether the in-app contact form is enabled |
+| `listing_id` / `tiny_id` / `listing_status` | Listing meta |
+| `brokers` | Full list of brokers (for the rare multi-agency case) |
+
+Raises `LookupError` if the listing has no contact info exposed.
+
+#### get_contact_form(listing)
+
+Get the agency's contact-form availability (which weekdays and times-of-day they accept inquiries through the in-app form).
+
+```python
+form = f.get_contact_form(43333315)
+print(form['days'], form['times_of_day'])
+# ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'] ['Morning', 'Afternoon']
+```
+
+**Returns:** Dict with `office_id`, `office_name`, `days`, `times_of_day`, `is_contacting_enabled`, `is_viewing_planner_enabled`, plus the raw `offices` list.
+
+#### get_listing_summary(listing)
+
+Lightweight version of `get_listing` (no descriptions, photos, kenmerken). Faster and smaller, useful for batch enrichment.
+
+```python
+summary = f.get_listing_summary(7985628)
+print(summary['title'], summary['price'], summary['energy_label'])
+# Semarangstraat 13 650000 C
+```
+
+**Returns:** A `Listing` object with summary fields (`title`, `price`, `living_area`, `plot_area`, `bedrooms`, `energy_label`, `broker_name`, `url`, `thumbnail_url`, …).
+
+#### get_similar_listings(listing)
+
+Get globalIds of similar / recently-sold listings near a given listing. Returns IDs only; combine with `get_listing_summary` or `get_listing` to materialize them.
+
+```python
+sim = f.get_similar_listings(7988952)
+for gid in sim['recently_sold']:
+    print(f.get_listing_summary(gid)['title'])
+```
+
+**Returns:** Dict with `recently_listed` and `recently_sold`, each a list of integer globalIds.
+
+#### get_market_insights(city, neighbourhood)
+
+Neighbourhood demographics and average asking €/m² for a (city, neighbourhood) pair. Accepts a `Listing` directly to use its city/neighbourhood automatically.
+
+```python
+mi = f.get_market_insights('Amsterdam', 'Twiske-West')
+# {'city': 'Amsterdam', 'neighbourhood': 'Twiske-West',
+#  'inhabitants': 2510, 'families_with_children_pct': 43.96,
+#  'avg_asking_price_per_m2': 5975}
+
+# Or pass a Listing
+listing = f.get_listing(43333315)
+mi = f.get_market_insights(listing)
+```
+
+**Returns:** Dict with `city`, `neighbourhood`, `inhabitants`, `families_with_children_pct`, `avg_asking_price_per_m2`. Raises `LookupError` for unknown neighbourhoods (HTTP 204).
+
+#### get_broker_info(broker)
+
+Get the agency's profile page: phone, email, website, postal address, affiliation (NVM/VBO/…), description, certificates, languages, services. Accepts a numeric `broker_id` or a `Listing` (uses its `broker_id` automatically).
+
+```python
+info = f.get_broker_info(24716)
+print(info['name'], info['phone'], info['email'])
+# Simone Dijkman Makelaardij 075 7725155 info@simonedijkman.nl
+
+# Or chain from a listing
+listing = f.get_listing(43333315)
+info = f.get_broker_info(listing)
+```
+
+#### get_broker_listings(broker)
+
+Every listing the agency has handled, tagged by status. Useful for analyzing an agency's deal history (sold dates, prices, neighbourhoods).
+
+```python
+listings = f.get_broker_listings(24716)
+sold = [l for l in listings if l['status'] == 'sold']
+for_sale = [l for l in listings if l['status'] == 'for_sale']
+print(f"{len(sold)} sold, {len(for_sale)} active")
+```
+
+**Returns:** Flat list of dicts. Each entry has `status` (`sold`, `for_sale`, `purchased`), `listing_id`, `tiny_id`, `title`, `street`, `house_number`, `postcode`, `city`, `latitude`, `longitude`, `price`, `price_formatted`, `price_condition`, `publication_date`, `transaction_date`, `image_url`, `detail_url`.
+
+#### get_broker_reviews(broker)
+
+Customer reviews and aggregate scores per agency. The API returns only a representative sample of recent reviews — `number_of_reviews` is the true total.
+
+```python
+r = f.get_broker_reviews(24716)
+print(f"{r['average']}/10 over {r['number_of_reviews']} reviews")
+for review in r['reviews']:
+    print(review['date'], review['average'], review['text'][:60])
+```
+
+**Returns:** Dict with `average` (float), `number_of_reviews`, `selectivity_percentage`, a single `highlight` review, and a `reviews` list. Each review has subscores (`expertise`, `local_market_knowledge`, `price_and_quality`, `service_and_guidance`, `average`), `transaction_type`, `text`, and `date`.
+
 ### Listing
 
 Listing objects support dict-like access with convenient aliases.

{pyfunda-2.6.2 → pyfunda-2.9.0}/funda/funda.py

@@ -16,6 +16,14 @@ 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"
+API_CONTACTS = "https://contacts-flows-bff.funda.io/api/v1/contacts-flows/listings/{listing_id}/contact-block"
+API_CONTACT_FORM = "https://contacts-bff.funda.io/api/v4/contact/listings/{listing_id}/contact-form"
+API_LISTING_SUMMARY = "https://listing-detail-summary.funda.io/api/v1/listing/nl/{global_id}"
+API_SIMILAR = "https://local-listings.funda.io/api/v1/similarlistings"
+API_MARKET_INSIGHTS = "https://marketinsights.funda.io/v2/localinsights/preview/{city}/{neighbourhood}"
+API_BROKER_INFO = "https://brokerpresentation-office-pages-bff.funda.io/api/v3.0/office-page/Wonen/{broker_id}/nl"
+API_BROKER_LISTINGS = "https://brokerpresentation-office-pages-bff.funda.io/api/v3.0/office-page/Wonen/{broker_id}/nl/listings"
+API_BROKER_REVIEWS = "https://reviews-office-pages-bff.funda.io/api/v1/office-page/{broker_id}/reviews/nl"
 API_WALTER = "https://api.walterliving.com/hunter/lookup"
 
 # Funda mobile app JA3 fingerprints (captured from real Dart/Flutter app traffic)
@@ -792,6 +800,561 @@ class Funda:
 
         return changes
 
+    def _resolve_global_id(self, listing: "Listing | int | str") -> int:
+        """Resolve any listing identifier to a numeric globalId.
+
+        Funda has two id systems: the 7-digit ``globalId`` used internally by
+        most APIs, and the 8-9 digit ``tinyId`` shown in funda.nl URLs. Many
+        endpoints (contact-block, listing-detail-summary, similarlistings,
+        contact-form) only accept the globalId, so tinyIds and URLs need to
+        be resolved through ``get_listing`` first.
+        """
+        if isinstance(listing, Listing):
+            gid = listing.get("global_id")
+            if not gid:
+                raise ValueError("Listing has no global_id")
+            return int(gid)
+        if isinstance(listing, str) and "funda.nl" in listing:
+            gid = self.get_listing(listing).get("global_id")
+            if not gid:
+                raise ValueError("Could not resolve URL to global_id")
+            return int(gid)
+        id_str = str(listing)
+        if not id_str.isdigit():
+            raise ValueError(f"Unrecognized listing identifier: {listing!r}")
+        if len(id_str) >= 8:  # tinyId — needs resolution
+            gid = self.get_listing(int(id_str)).get("global_id")
+            if not gid:
+                raise ValueError(f"Could not resolve tinyId {id_str}")
+            return int(gid)
+        return int(id_str)
+
+    def get_contact_info(self, listing: "Listing | int | str") -> dict:
+        """Get realtor/makelaar contact info for a listing.
+
+        Returns the agency name, phone number, and association code as exposed
+        by the Funda Android app's contact block endpoint.
+
+        Args:
+            listing: A Listing object, a numeric id (globalId or tinyId), or a
+                Funda URL. tinyIds and URLs are resolved to a globalId via
+                ``get_listing`` before the contact lookup.
+
+        Returns:
+            Dict with the primary broker hoisted to the top level for
+            ergonomics (``name``, ``phone``, ``broker_id``, ``association``)
+            plus listing meta (``listing_id``, ``tiny_id``, ``listing_status``)
+            and the full ``brokers`` list for the rare multi-agency case.
+
+        Raises:
+            LookupError: Listing exists but has no contact info (HTTP 204) or
+                the endpoint returned a non-200 status.
+
+        Example:
+            >>> listing = f.get_listing(43333315)
+            >>> contact = f.get_contact_info(listing)
+            >>> contact['name'], contact['phone']
+            ('Scheffer Makelaardij B.V.', '020-2470322')
+        """
+        global_id = self._resolve_global_id(listing)
+        url = API_CONTACTS.format(listing_id=global_id)
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code == 204:
+            raise LookupError(f"Listing {global_id} has no contact info")
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch contact info (status {response.status_code})"
+            )
+
+        return self._parse_contact_info(response.json())
+
+    def get_contact_form(self, listing: "Listing | int | str") -> dict:
+        """Get contact-form availability (days and times-of-day) for a listing.
+
+        Companion to ``get_contact_info``. Tells you which weekdays and
+        times-of-day the agency accepts inquiries through the in-app form.
+
+        Returns:
+            Dict with the primary office hoisted to the top level
+            (``office_id``, ``office_name``, ``days``, ``times_of_day``,
+            ``is_contacting_enabled``, ``is_viewing_planner_enabled``) plus
+            the raw ``offices`` list.
+
+        Example:
+            >>> form = f.get_contact_form(43333315)
+            >>> form['days']
+            ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday']
+            >>> form['times_of_day']
+            ['Morning', 'Afternoon']
+        """
+        global_id = self._resolve_global_id(listing)
+        url = API_CONTACT_FORM.format(listing_id=global_id)
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code == 204:
+            raise LookupError(f"Listing {global_id} has no contact form")
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch contact form (status {response.status_code})"
+            )
+
+        data = response.json()
+        if not data:
+            raise LookupError(f"No contact form entries for listing {global_id}")
+
+        primary = data[0]
+        return {
+            "office_id": primary.get("officeId"),
+            "office_name": primary.get("officeName"),
+            "is_contacting_enabled": primary.get("isContactingEnabled"),
+            "is_viewing_planner_enabled": primary.get("isViewingPlannerEnabled"),
+            "days": primary.get("days", []),
+            "times_of_day": primary.get("timesOfDay", []),
+            "offices": data,
+        }
+
+    def get_listing_summary(self, listing: "Listing | int | str") -> Listing:
+        """Get a lightweight summary of a listing.
+
+        Faster and smaller than ``get_listing`` (no descriptions, photos, or
+        kenmerken). Useful for batch enrichment, e.g. fetching a row of
+        ``get_similar_listings`` results.
+
+        Returns:
+            Listing object with summary fields populated.
+
+        Example:
+            >>> summary = f.get_listing_summary(7985628)
+            >>> summary['title'], summary['price'], summary['energy_label']
+            ('Semarangstraat 13', 650000, 'C')
+        """
+        global_id = self._resolve_global_id(listing)
+        url = API_LISTING_SUMMARY.format(global_id=global_id)
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code == 404:
+            raise LookupError(f"Listing summary {global_id} not found")
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch listing summary (status {response.status_code})"
+            )
+
+        return self._parse_listing_summary(response.json())
+
+    def get_similar_listings(self, listing: "Listing | int | str") -> dict:
+        """Get globalIds of similar / recently-sold listings near this one.
+
+        Returns IDs only. Combine with ``get_listing_summary`` or
+        ``get_listing`` to materialize them.
+
+        Returns:
+            Dict with ``recently_listed`` and ``recently_sold``, each a list
+            of integer globalIds.
+
+        Example:
+            >>> sim = f.get_similar_listings(7988952)
+            >>> [f.get_listing_summary(gid)['title'] for gid in sim['recently_sold'][:3]]
+        """
+        global_id = self._resolve_global_id(listing)
+        url = f"{API_SIMILAR}?globalId={global_id}"
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch similar listings (status {response.status_code})"
+            )
+
+        data = response.json()
+        return {
+            "recently_listed": [int(x["globalId"]) for x in data.get("recentlyListed", []) if x.get("globalId")],
+            "recently_sold": [int(x["globalId"]) for x in data.get("recentlySold", []) if x.get("globalId")],
+        }
+
+    def get_market_insights(
+        self,
+        city: "str | Listing",
+        neighbourhood: str | None = None,
+    ) -> dict:
+        """Get neighbourhood demographics and average €/m² for a location.
+
+        Args:
+            city: Either a city name (string) or a Listing object, in which
+                case ``city`` and ``neighbourhood`` are taken from the
+                listing automatically.
+            neighbourhood: Neighbourhood name. Required if ``city`` is a
+                string; ignored if ``city`` is a Listing.
+
+        Returns:
+            Dict with ``city``, ``neighbourhood``, ``inhabitants``,
+            ``families_with_children_pct``, ``avg_asking_price_per_m2``.
+
+        Example:
+            >>> f.get_market_insights('Amsterdam', 'Twiske-West')
+            {'city': 'Amsterdam', 'neighbourhood': 'Twiske-West',
+             'inhabitants': 2510, 'families_with_children_pct': 43.96,
+             'avg_asking_price_per_m2': 5975}
+            >>> # Or pass a Listing directly
+            >>> listing = f.get_listing(43333315)
+            >>> f.get_market_insights(listing)
+        """
+        if isinstance(city, Listing):
+            city_name = city.get("city") or ""
+            nb_name = city.get("neighbourhood") or ""
+            if not city_name or not nb_name:
+                raise ValueError(
+                    "Listing must have city and neighbourhood for market insights"
+                )
+        else:
+            if not neighbourhood:
+                raise ValueError("neighbourhood is required when city is a string")
+            city_name = city
+            nb_name = neighbourhood
+
+        city_slug = city_name.lower().replace(" ", "-")
+        nb_slug = nb_name.lower().replace(" ", "-")
+
+        url = API_MARKET_INSIGHTS.format(city=city_slug, neighbourhood=nb_slug)
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code == 204:
+            raise LookupError(
+                f"No market insights for {city_slug}/{nb_slug}"
+            )
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch market insights (status {response.status_code})"
+            )
+
+        data = response.json()
+        return {
+            "city": data.get("city"),
+            "neighbourhood": data.get("neighbourhood"),
+            "inhabitants": data.get("inhabitants"),
+            "families_with_children_pct": data.get("familiesWithChildren"),
+            "avg_asking_price_per_m2": data.get("averageAskingPricePerM2"),
+        }
+
+    def _resolve_broker_id(self, broker: "Listing | int | str") -> int:
+        """Resolve a broker reference (Listing, int, or numeric str) to an id.
+
+        The broker id (Funda calls it ``officeId``, internally ``broker_id``
+        on Listing objects) is shared across the broker-page endpoints.
+        """
+        if isinstance(broker, Listing):
+            bid = broker.get("broker_id")
+            if not bid:
+                raise ValueError("Listing has no broker_id")
+            return int(bid)
+        id_str = str(broker)
+        if not id_str.isdigit():
+            raise ValueError(f"Unrecognized broker identifier: {broker!r}")
+        return int(id_str)
+
+    def get_broker_info(self, broker: "Listing | int | str") -> dict:
+        """Get a broker/agency profile page (phone, email, website, etc).
+
+        Args:
+            broker: A Listing object (uses its ``broker_id``) or a numeric
+                broker id (also called ``officeId`` in the Funda app).
+
+        Returns:
+            Dict with the agency's display name, phone, email, website,
+            postal address, affiliation (NVM/VBO/…), description (HTML),
+            certificates, languages, services, and logo image URL set.
+
+        Raises:
+            LookupError: Unknown broker id (HTTP 204) or non-200.
+
+        Example:
+            >>> info = f.get_broker_info(24716)
+            >>> info['name'], info['phone'], info['email']
+            ('Simone Dijkman Makelaardij', '075 7725155', 'info@simonedijkman.nl')
+        """
+        broker_id = self._resolve_broker_id(broker)
+        url = API_BROKER_INFO.format(broker_id=broker_id)
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code == 204:
+            raise LookupError(f"Broker {broker_id} not found")
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch broker info (status {response.status_code})"
+            )
+
+        return self._parse_broker_info(response.json())
+
+    def get_broker_listings(self, broker: "Listing | int | str") -> list[dict]:
+        """Get every listing handled by a broker (sold, for-sale, purchased).
+
+        Returns a flat list of listing entries with a ``status`` field
+        ("sold", "for_sale", or "purchased"). Each entry includes price,
+        address, lat/lng, image, dates, and the ``tiny_id`` parsed from the
+        detail URL.
+
+        Returns:
+            List of dicts, one per listing, sorted as the API returns them.
+
+        Example:
+            >>> listings = f.get_broker_listings(24716)
+            >>> sold = [l for l in listings if l['status'] == 'sold']
+            >>> len(sold), sold[0]['title'], sold[0]['transaction_date']
+        """
+        broker_id = self._resolve_broker_id(broker)
+        url = API_BROKER_LISTINGS.format(broker_id=broker_id)
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code == 204:
+            raise LookupError(f"Broker {broker_id} has no listings")
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch broker listings (status {response.status_code})"
+            )
+
+        return self._parse_broker_listings(response.json())
+
+    def get_broker_reviews(self, broker: "Listing | int | str") -> dict:
+        """Get customer reviews and aggregate scores for a broker.
+
+        Note that the API only returns a small sample of recent reviews,
+        not the full set — ``number_of_reviews`` reflects the total, while
+        ``reviews`` is a representative slice.
+
+        Returns:
+            Dict with aggregate ``average`` (float), ``number_of_reviews``,
+            ``selectivity_percentage``, a ``highlight`` review, and a list
+            of ``reviews`` (each with subscores, transaction_type, text).
+
+        Example:
+            >>> r = f.get_broker_reviews(24716)
+            >>> r['average'], r['number_of_reviews']
+            (9.3, 26)
+        """
+        broker_id = self._resolve_broker_id(broker)
+        url = API_BROKER_REVIEWS.format(broker_id=broker_id)
+        headers = _make_headers()
+        response = self._get(url, headers)
+
+        if response.status_code == 204:
+            raise LookupError(f"Broker {broker_id} has no reviews")
+        if response.status_code != 200:
+            raise LookupError(
+                f"Could not fetch broker reviews (status {response.status_code})"
+            )
+
+        return self._parse_broker_reviews(response.json())
+
+    def _parse_contact_info(self, data: dict) -> dict:
+        """Normalize the contact-block payload into a flat dict."""
+        brokers = [
+            {
+                "broker_id": b.get("id"),
+                "name": b.get("displayName"),
+                "phone": b.get("phoneNumber"),
+                "association": b.get("associationCode"),
+                "logo_url": b.get("logoUrl") or None,
+                "banner_url": b.get("bannerUrl"),
+                "is_contacting_enabled": b.get("isContactingEnabled"),
+                "personal_contact_info": b.get("personalContactBlockInfo"),
+            }
+            for b in data.get("contactBlockDetails", [])
+        ]
+
+        result: dict[str, Any] = {
+            "listing_id": data.get("id"),
+            "tiny_id": data.get("tinyId"),
+            "listing_status": data.get("listingStatus"),
+            "is_viewing_planner_enabled": data.get("isViewingPlannerEnabled"),
+            "brokers": brokers,
+        }
+
+        # Hoist primary broker fields to the top level (single-agency is the
+        # overwhelming common case).
+        if brokers:
+            primary = brokers[0]
+            result.update({
+                "broker_id": primary["broker_id"],
+                "name": primary["name"],
+                "phone": primary["phone"],
+                "association": primary["association"],
+                "logo_url": primary["logo_url"],
+                "banner_url": primary["banner_url"],
+                "is_contacting_enabled": primary["is_contacting_enabled"],
+                "personal_contact_info": primary["personal_contact_info"],
+            })
+
+        return result
+
+    def _parse_listing_summary(self, data: dict) -> Listing:
+        """Parse the lightweight listing-detail-summary payload."""
+        ids = data.get("identifiers", {})
+        addr = data.get("address", {})
+        fast = data.get("fastView", {})
+        price = data.get("price", {})
+        media = data.get("media", {})
+        brokers = data.get("brokers", []) or []
+        primary_broker = brokers[0] if brokers else {}
+        urls = data.get("urls", {}).get("friendlyUrl", {})
+        promo = data.get("promo", {}).get("blikvanger", {}) or {}
+        tracking = data.get("tracking", {}).get("values", {}) or {}
+
+        photo_base = media.get("thumbnailBaseUrl", "") or ""
+        photo_id = media.get("id")
+        thumbnail_url = None
+        if photo_base and photo_id:
+            thumbnail_url = photo_base.replace("{id}", str(photo_id)).replace(
+                "{size}", "720x480"
+            )
+
+        listing_data = {
+            "global_id": ids.get("globalId"),
+            "tiny_id": ids.get("tinyId"),
+            "title": addr.get("title"),
+            "subtitle": addr.get("subTitle"),
+            "city": addr.get("city"),
+            "postcode": addr.get("postCode"),
+            "price_formatted": price.get("sellingPrice") or price.get("rentalPrice"),
+            "price": tracking.get("listing_askingprice"),
+            "living_area_formatted": fast.get("livingArea"),
+            "living_area": _parse_area(fast.get("livingArea")),
+            "plot_area_formatted": fast.get("plotArea"),
+            "plot_area": _parse_area(fast.get("plotArea")),
+            "bedrooms": fast.get("numberOfBedrooms"),
+            "energy_label": fast.get("energyLabel"),
+            "object_type": tracking.get("listing_type"),
+            "offering_type": tracking.get("listing_offering_type"),
+            "status": tracking.get("listing_status"),
+            "is_sold_or_rented": data.get("isSoldOrRented"),
+            "publication_date": data.get("publicationDate"),
+            "highlight": promo.get("text"),
+            "broker_id": primary_broker.get("officeId"),
+            "broker_name": primary_broker.get("name"),
+            "url": urls.get("fullUrl"),
+            "share_url": data.get("share", {}).get("url"),
+            "thumbnail_url": thumbnail_url,
+        }
+
+        return Listing(
+            listing_id=ids.get("tinyId") or ids.get("globalId"),
+            data=listing_data,
+        )
+
+    def _parse_broker_info(self, data: dict) -> dict:
+        """Normalize the broker office-page payload."""
+        office = data.get("officeId", {}) or {}
+        desc = data.get("description", {}) or {}
+        contact = data.get("contactDetails", {}) or {}
+        addr = contact.get("address", {}) or {}
+        media = data.get("mediaReferences", {}) or {}
+        chars = data.get("characteristics", {}) or {}
+
+        return {
+            "broker_id": office.get("officeNumber"),
+            "uuid": office.get("id"),
+            "name": data.get("displayName"),
+            "affiliation": data.get("affiliation"),
+            "slogan": desc.get("slogan"),
+            "description": desc.get("description"),
+            "short_description": desc.get("shortDescription"),
+            "email": contact.get("email"),
+            "website": contact.get("websiteUrl"),
+            "phone": contact.get("phoneNumber"),
+            "address": {
+                "street": addr.get("street"),
+                "number": addr.get("number"),
+                "addition": addr.get("addition"),
+                "postcode": addr.get("postcode"),
+                "city": addr.get("location"),
+            },
+            "logo_urls": media.get("logoImages") or None,
+            "languages": chars.get("languages", []),
+            "services": chars.get("services", []),
+            "certificates": chars.get("certificates", []),
+        }
+
+    def _parse_broker_listings(self, data: dict) -> list[dict]:
+        """Flatten the broker-listings payload into a list tagged by status."""
+        status_map = {
+            "Sold": "sold",
+            "ForSale": "for_sale",
+            "Purchased": "purchased",
+        }
+        tiny_re = re.compile(r"/detail/(\d+)/?")
+
+        out = []
+        for group in data.get("offering", []) or []:
+            api_status = group.get("type")
+            status = status_map.get(api_status, api_status.lower() if api_status else None)
+            for item in group.get("listings", []) or []:
+                loc = item.get("location", {}) or {}
+                addr = loc.get("address", {}) or {}
+                detail_url = item.get("detailUrl") or ""
+                tiny_match = tiny_re.search(detail_url)
+                street = addr.get("street") or ""
+                number = addr.get("number") or ""
+                addition = addr.get("addition") or ""
+                title = f"{street} {number}".strip()
+                if addition:
+                    title = f"{title}-{addition}" if number else f"{title} {addition}".strip()
+                out.append({
+                    "status": status,
+                    "listing_id": item.get("listingId"),
+                    "tiny_id": tiny_match.group(1) if tiny_match else None,
+                    "title": title or None,
+                    "street": addr.get("street"),
+                    "house_number": addr.get("number"),
+                    "house_number_ext": addr.get("addition") or None,
+                    "postcode": addr.get("postcode"),
+                    "city": addr.get("city"),
+                    "latitude": loc.get("latitude"),
+                    "longitude": loc.get("longitude"),
+                    "price": item.get("price"),
+                    "price_formatted": item.get("formattedPrice"),
+                    "price_type": item.get("priceType"),
+                    "price_condition": item.get("priceCondition"),
+                    "publication_date": item.get("publicationDate"),
+                    "transaction_date": item.get("transactionDate"),
+                    "image_url": item.get("image"),
+                    "detail_url": (
+                        f"https://www.funda.nl{detail_url}" if detail_url.startswith("/") else detail_url
+                    ) or None,
+                })
+        return out
+
+    def _parse_broker_reviews(self, data: dict) -> dict:
+        """Normalize the broker reviews payload."""
+        scores = data.get("scores", {}) or {}
+
+        def _flatten(review: dict | None) -> dict | None:
+            if not review:
+                return None
+            score = review.get("score", {}) or {}
+            return {
+                "date": review.get("postedDate"),
+                "transaction_type": review.get("transactionType"),
+                "text": review.get("text"),
+                "average": score.get("average"),
+                "expertise": score.get("expertise"),
+                "local_market_knowledge": score.get("localMarketKnowledge"),
+                "price_and_quality": score.get("priceAndQuality"),
+                "service_and_guidance": score.get("serviceAndGuidance"),
+            }
+
+        return {
+            "average": scores.get("average"),
+            "number_of_reviews": scores.get("numberOfReviews"),
+            "selectivity_percentage": scores.get("selectivityPercentage"),
+            "highlight": _flatten(data.get("highlightedReview")),
+            "reviews": [_flatten(r) for r in data.get("reviews", []) or []],
+        }
+
     def _parse_search_results(self, data: dict) -> list[Listing]:
         """Parse search API response into list of Listings."""
         listings = []

{pyfunda-2.6.2 → pyfunda-2.9.0}/pyproject.toml

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

{pyfunda-2.6.2 → pyfunda-2.9.0}/test_all_flows.py

@@ -757,6 +757,253 @@ def test_listing_setitem():
     print("  setitem working correctly")
 
 
+# =============================================================================
+# FLOW 18: Realtor Contact Info
+# =============================================================================
+
+@test("Get contact info by globalId")
+def test_get_contact_info_by_global_id():
+    from funda import Funda
+    f = Funda()
+    contact = f.get_contact_info(7988952)
+
+    assert contact['name'], "Should have agency name"
+    assert contact['phone'], "Should have phone number"
+    assert contact['broker_id'], "Should have broker_id"
+    assert contact['listing_id'] == '7988952', "Should echo listing_id"
+    assert contact['tiny_id'] == '43333315', "Should include tiny_id"
+    assert isinstance(contact['brokers'], list) and contact['brokers'], "Should have brokers list"
+    print(f"  {contact['name']} | {contact['phone']}")
+
+
+@test("Get contact info by Listing object")
+def test_get_contact_info_by_listing():
+    from funda import Funda
+    f = Funda()
+    listing = f.get_listing(43333315)
+    contact = f.get_contact_info(listing)
+
+    assert contact['phone'], "Should have phone number"
+    assert contact['name'], "Should have agency name"
+    print(f"  {contact['name']} | {contact['phone']}")
+
+
+@test("Get contact info by tinyId resolves to globalId")
+def test_get_contact_info_by_tiny_id():
+    from funda import Funda
+    f = Funda()
+    contact = f.get_contact_info(43333315)
+
+    assert contact['listing_id'] == '7988952', "tinyId should resolve to globalId"
+    assert contact['phone'], "Should have phone number"
+
+
+@test("Get contact info raises LookupError for unknown listing")
+def test_get_contact_info_not_found():
+    from funda import Funda
+    f = Funda()
+
+    try:
+        f.get_contact_info(1)
+        assert False, "Should have raised LookupError"
+    except LookupError as e:
+        assert "no contact info" in str(e).lower() or "could not fetch" in str(e).lower()
+        print(f"  Correctly raised: {e}")
+
+
+# =============================================================================
+# FLOW 19: Contact Form Availability
+# =============================================================================
+
+@test("Get contact form returns days and times of day")
+def test_get_contact_form():
+    from funda import Funda
+    f = Funda()
+    form = f.get_contact_form(7988952)
+
+    assert form['office_name'], "Should have office name"
+    assert form['office_id'], "Should have office id"
+    assert isinstance(form['days'], list) and form['days'], "Should have days list"
+    assert isinstance(form['times_of_day'], list) and form['times_of_day'], "Should have times_of_day"
+    assert isinstance(form['offices'], list) and form['offices'], "Should expose raw offices list"
+    print(f"  {form['office_name']} | days={form['days']} | times={form['times_of_day']}")
+
+
+# =============================================================================
+# FLOW 20: Lightweight Listing Summary
+# =============================================================================
+
+@test("Get listing summary by globalId")
+def test_get_listing_summary_by_global_id():
+    from funda import Funda, Listing
+    f = Funda()
+    summary = f.get_listing_summary(7985628)
+
+    assert isinstance(summary, Listing), "Should return Listing instance"
+    assert summary['title'], "Should have title"
+    assert summary['price'], "Should have numeric price"
+    assert summary['energy_label'], "Should have energy_label"
+    assert summary['url'].startswith("https://www.funda.nl/"), "Should have full URL"
+    assert summary['broker_name'], "Should have broker_name"
+    print(f"  {summary['title']} | €{summary['price']} | label {summary['energy_label']}")
+
+
+@test("Get listing summary resolves tinyId via get_listing")
+def test_get_listing_summary_by_tiny_id():
+    from funda import Funda
+    f = Funda()
+    summary = f.get_listing_summary(43333315)
+
+    assert summary['global_id'] == 7988952, "tinyId should resolve to globalId 7988952"
+
+
+@test("Get listing summary raises LookupError for unknown id")
+def test_get_listing_summary_not_found():
+    from funda import Funda
+    f = Funda()
+
+    try:
+        f.get_listing_summary(1)
+        assert False, "Should have raised LookupError"
+    except LookupError as e:
+        print(f"  Correctly raised: {e}")
+
+
+# =============================================================================
+# FLOW 21: Similar Listings
+# =============================================================================
+
+@test("Get similar listings returns globalId lists")
+def test_get_similar_listings():
+    from funda import Funda
+    f = Funda()
+    sim = f.get_similar_listings(7988952)
+
+    assert "recently_listed" in sim and "recently_sold" in sim, "Should have both keys"
+    assert all(isinstance(x, int) for x in sim['recently_listed']), "recently_listed should be list of ints"
+    assert all(isinstance(x, int) for x in sim['recently_sold']), "recently_sold should be list of ints"
+    print(f"  listed={sim['recently_listed']} sold={sim['recently_sold']}")
+
+
+# =============================================================================
+# FLOW 22: Local Market Insights
+# =============================================================================
+
+@test("Get market insights by city and neighbourhood")
+def test_get_market_insights_by_strings():
+    from funda import Funda
+    f = Funda()
+    mi = f.get_market_insights('Amsterdam', 'Twiske-West')
+
+    assert mi['city'] == 'Amsterdam', "city should round-trip"
+    assert mi['neighbourhood'] == 'Twiske-West', "neighbourhood should round-trip"
+    assert isinstance(mi['inhabitants'], int) and mi['inhabitants'] > 0
+    assert isinstance(mi['avg_asking_price_per_m2'], (int, float)) and mi['avg_asking_price_per_m2'] > 0
+    print(f"  {mi['city']}/{mi['neighbourhood']}: {mi['inhabitants']} inhab, €{mi['avg_asking_price_per_m2']}/m²")
+
+
+@test("Get market insights from a Listing object")
+def test_get_market_insights_from_listing():
+    from funda import Funda
+    f = Funda()
+    listing = f.get_listing(43333315)
+    mi = f.get_market_insights(listing)
+
+    assert mi['city'], "Should have city"
+    assert mi['neighbourhood'], "Should have neighbourhood"
+
+
+@test("Get market insights raises LookupError for unknown neighbourhood")
+def test_get_market_insights_not_found():
+    from funda import Funda
+    f = Funda()
+
+    try:
+        f.get_market_insights('Amsterdam', 'Nope-Nope-Nope')
+        assert False, "Should have raised LookupError"
+    except LookupError as e:
+        print(f"  Correctly raised: {e}")
+
+
+# =============================================================================
+# FLOW 23: Broker Profile, Listings, and Reviews
+# =============================================================================
+
+@test("Get broker info by id")
+def test_get_broker_info():
+    from funda import Funda
+    f = Funda()
+    info = f.get_broker_info(24716)
+
+    assert info['name'], "Should have agency name"
+    assert info['phone'], "Should have phone"
+    assert info['email'], "Should have email"
+    assert info['affiliation'], "Should have affiliation"
+    assert isinstance(info['address'], dict) and info['address']['city'], "Should have address"
+    assert isinstance(info['languages'], list)
+    assert isinstance(info['services'], list)
+    assert isinstance(info['certificates'], list)
+    print(f"  {info['name']} | {info['phone']} | {info['email']} ({info['affiliation']})")
+
+
+@test("Get broker info via Listing object")
+def test_get_broker_info_via_listing():
+    from funda import Funda
+    f = Funda()
+    listing = f.get_listing(43333315)
+    info = f.get_broker_info(listing)
+
+    assert info['broker_id'] == listing.get('broker_id'), "broker_id should round-trip"
+    assert info['name'], "Should have agency name"
+
+
+@test("Get broker info raises LookupError for unknown id")
+def test_get_broker_info_not_found():
+    from funda import Funda
+    f = Funda()
+
+    try:
+        f.get_broker_info(99999999)
+        assert False, "Should have raised LookupError"
+    except LookupError as e:
+        print(f"  Correctly raised: {e}")
+
+
+@test("Get broker listings returns flat tagged list")
+def test_get_broker_listings():
+    from funda import Funda
+    f = Funda()
+    listings = f.get_broker_listings(24716)
+
+    assert isinstance(listings, list) and listings, "Should be non-empty list"
+    statuses = {l['status'] for l in listings}
+    assert statuses, "Should have at least one status"
+    assert all(l.get('listing_id') for l in listings), "All entries should have listing_id"
+    sold = [l for l in listings if l['status'] == 'sold']
+    if sold:
+        s = sold[0]
+        assert s['transaction_date'], "Sold listings should have transaction_date"
+        assert s['tiny_id'], "Should parse tiny_id from detailUrl"
+        assert s['detail_url'].startswith('https://www.funda.nl/'), "Should have absolute URL"
+    print(f"  {len(listings)} listings | statuses={statuses}")
+
+
+@test("Get broker reviews returns aggregate scores and review list")
+def test_get_broker_reviews():
+    from funda import Funda
+    f = Funda()
+    r = f.get_broker_reviews(24716)
+
+    assert isinstance(r['average'], (int, float)), "Should have numeric average"
+    assert isinstance(r['number_of_reviews'], int) and r['number_of_reviews'] >= 1
+    assert isinstance(r['reviews'], list)
+    if r['reviews']:
+        first = r['reviews'][0]
+        for k in ['average', 'expertise', 'local_market_knowledge', 'price_and_quality', 'service_and_guidance']:
+            assert k in first, f"Review should have {k}"
+    print(f"  avg={r['average']} | n={r['number_of_reviews']} | selectivity={r['selectivity_percentage']}%")
+
+
 # =============================================================================
 # Run all tests
 # =============================================================================
@@ -849,6 +1096,35 @@ def run_all_tests():
 
         # Flow 17: Listing Set Item
         test_listing_setitem,
+
+        # Flow 18: Realtor Contact Info
+        test_get_contact_info_by_global_id,
+        test_get_contact_info_by_listing,
+        test_get_contact_info_by_tiny_id,
+        test_get_contact_info_not_found,
+
+        # Flow 19: Contact Form Availability
+        test_get_contact_form,
+
+        # Flow 20: Lightweight Listing Summary
+        test_get_listing_summary_by_global_id,
+        test_get_listing_summary_by_tiny_id,
+        test_get_listing_summary_not_found,
+
+        # Flow 21: Similar Listings
+        test_get_similar_listings,
+
+        # Flow 22: Local Market Insights
+        test_get_market_insights_by_strings,
+        test_get_market_insights_from_listing,
+        test_get_market_insights_not_found,
+
+        # Flow 23: Broker profile, listings, reviews
+        test_get_broker_info,
+        test_get_broker_info_via_listing,
+        test_get_broker_info_not_found,
+        test_get_broker_listings,
+        test_get_broker_reviews,
     ]
 
     start_time = time.time()