pyfunda 2.6.2__tar.gz → 2.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfunda
-Version: 2.6.2
+Version: 2.7.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,32 @@ 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.
+
 ### Listing
 
 Listing objects support dict-like access with convenient aliases.

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

@@ -283,6 +283,32 @@ 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.
+
 ### Listing
 
 Listing objects support dict-like access with convenient aliases.

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

@@ -16,6 +16,7 @@ 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_WALTER = "https://api.walterliving.com/hunter/lookup"
 
 # Funda mobile app JA3 fingerprints (captured from real Dart/Flutter app traffic)
@@ -792,6 +793,108 @@ class Funda:
 
         return changes
 
+    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')
+        """
+        # Resolve to global_id (the endpoint expects the numeric listingId,
+        # not the tinyId shown in funda.nl URLs).
+        global_id: int | None = None
+        if isinstance(listing, Listing):
+            global_id = listing.get("global_id")
+        elif isinstance(listing, str) and "funda.nl" in listing:
+            global_id = self.get_listing(listing).get("global_id")
+        else:
+            id_str = str(listing)
+            if not id_str.isdigit():
+                raise ValueError(f"Unrecognized listing identifier: {listing!r}")
+            # tinyIds are 8-9 digits; resolve them to a globalId via the
+            # listing detail endpoint. 7-digit ids are already globalIds.
+            if len(id_str) >= 8:
+                global_id = self.get_listing(int(id_str)).get("global_id")
+            else:
+                global_id = int(id_str)
+
+        if not global_id:
+            raise ValueError("Could not determine listing globalId")
+
+        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 _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_search_results(self, data: dict) -> list[Listing]:
         """Parse search API response into list of Listings."""
         listings = []

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyfunda"
-version = "2.6.2"
+version = "2.7.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.7.0}/test_all_flows.py

@@ -757,6 +757,60 @@ 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}")
+
+
 # =============================================================================
 # Run all tests
 # =============================================================================
@@ -849,6 +903,12 @@ 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,
     ]
 
     start_time = time.time()