Add residential sub-object to anonymizer for Insights

HISTORY.rst

@@ -14,6 +14,13 @@ History
   ``aiohttp.encode_basic_auth()`` instead of the ``aiohttp.BasicAuth`` /
   ``auth=`` parameter, which are deprecated as of aiohttp 3.14.0. As a result,
   the minimum required ``aiohttp`` version is now 3.14.0.
+* A new ``residential`` attribute has been added to
+  ``geoip2.records.Anonymizer``. This is a ``geoip2.records.AnonymizerFeed``
+  object providing residential proxy data for the network and contains the
+  following fields: ``confidence``, ``network_last_seen``, and
+  ``provider_name``. This attribute may be populated even when no other
+  anonymizer attributes are set, so the ``anonymizer`` object may now
+  contain only this attribute.
 
 5.2.0 (2025-11-20)
 ++++++++++++++++++

src/geoip2/records.py

@@ -262,11 +262,58 @@ def __init__(self, *, queries_remaining: int | None = None, **_: Any) -> None:
         self.queries_remaining = queries_remaining
 
 
+class AnonymizerFeed(Record):
+    """Contains data for one type of anonymizer detection.
+
+    This class contains data for one type of anonymizer detection,
+    currently residential proxies. Additional feeds may be added in the
+    future.
+
+    This record is returned by ``insights`` as the ``residential`` attribute
+    of :py:class:`Anonymizer`.
+    """
+
+    confidence: int | None
+    """A score ranging from 1 to 99 that represents our percent confidence
+    that the network is an actively used residential proxy. This attribute
+    is only available from the Insights end point.
+    """
+
+    network_last_seen: datetime.date | None
+    """The last day that the network was sighted in our analysis of
+    residential proxies. This attribute is only available from the Insights
+    end point.
+    """
+
+    provider_name: str | None
+    """The name of the residential proxy provider associated with the
+    network. This attribute is only available from the Insights end point.
+    """
+
+    def __init__(
+        self,
+        *,
+        confidence: int | None = None,
+        network_last_seen: str | None = None,
+        provider_name: str | None = None,
+        **_: Any,
+    ) -> None:
+        self.confidence = confidence
+        self.network_last_seen = (
+            datetime.date.fromisoformat(network_last_seen)
+            if network_last_seen
+            else None
+        )
+        self.provider_name = provider_name
+
+
 class Anonymizer(Record):
     """Contains data for the anonymizer record associated with an IP address.
 
     This class contains the anonymizer data associated with an IP address.
 
+    Note that this object may contain only the ``residential`` attribute.
+
     This record is returned by ``insights``.
     """
 
@@ -288,6 +335,12 @@ class Anonymizer(Record):
     point.
     """
 
+    residential: AnonymizerFeed
+    """Residential proxy data for the network associated with the IP address.
+    This may be populated even when no other anonymizer attributes are set.
+    This attribute is only available from the Insights end point.
+    """
+
     is_anonymous: bool
     """This is true if the IP address belongs to any sort of anonymous network.
     This attribute is only available from the Insights end point.
@@ -337,6 +390,7 @@ def __init__(
         is_tor_exit_node: bool = False,
         network_last_seen: str | None = None,
         provider_name: str | None = None,
+        residential: dict[str, Any] | None = None,
         **_: Any,
     ) -> None:
         self.confidence = confidence
@@ -352,6 +406,7 @@ def __init__(
             else None
         )
         self.provider_name = provider_name
+        self.residential = AnonymizerFeed(**(residential or {}))
 
 
 class Postal(Record):

tests/models_test.py

@@ -1,3 +1,4 @@
+import datetime
 import ipaddress
 import sys
 import unittest
@@ -24,6 +25,11 @@ def test_insights_full(self) -> None:  # noqa: PLR0915
                 "is_tor_exit_node": True,
                 "network_last_seen": "2025-04-14",
                 "provider_name": "FooBar VPN",
+                "residential": {
+                    "confidence": 82,
+                    "network_last_seen": "2026-05-11",
+                    "provider_name": "quickshift",
+                },
             },
             "city": {
                 "confidence": 76,
@@ -262,10 +268,23 @@ def test_insights_full(self) -> None:  # noqa: PLR0915
         self.assertIs(model.anonymizer.is_tor_exit_node, True)
         self.assertEqual(
             model.anonymizer.network_last_seen,
-            __import__("datetime").date(2025, 4, 14),
+            datetime.date(2025, 4, 14),
         )
         self.assertEqual(model.anonymizer.provider_name, "FooBar VPN")
 
+        # Test anonymizer.residential object
+        self.assertEqual(
+            type(model.anonymizer.residential),
+            geoip2.records.AnonymizerFeed,
+            "geoip2.records.AnonymizerFeed object",
+        )
+        self.assertEqual(model.anonymizer.residential.confidence, 82)
+        self.assertEqual(
+            model.anonymizer.residential.network_last_seen,
+            datetime.date(2026, 5, 11),
+        )
+        self.assertEqual(model.anonymizer.residential.provider_name, "quickshift")
+
     def test_insights_min(self) -> None:
         model = geoip2.models.Insights(["en"], traits={"ip_address": "5.6.7.8"})
         self.assertEqual(
@@ -324,6 +343,40 @@ def test_insights_min(self) -> None:
         self.assertIsNone(model.anonymizer.provider_name)
         self.assertFalse(model.anonymizer.is_anonymous)
         self.assertFalse(model.anonymizer.is_anonymous_vpn)
+        # Test that anonymizer.residential defaults correctly
+        self.assertEqual(
+            type(model.anonymizer.residential),
+            geoip2.records.AnonymizerFeed,
+            "geoip2.records.AnonymizerFeed object",
+        )
+        self.assertIsNone(model.anonymizer.residential.confidence)
+        self.assertIsNone(model.anonymizer.residential.network_last_seen)
+        self.assertIsNone(model.anonymizer.residential.provider_name)
+
+    def test_insights_anonymizer_residential_only(self) -> None:
+        # The residential attribute may be populated even when no other
+        # anonymizer attributes are set, so the anonymizer object may
+        # contain only the residential attribute.
+        model = geoip2.models.Insights(
+            ["en"],
+            anonymizer={
+                "residential": {
+                    "confidence": 82,
+                    "network_last_seen": "2026-05-11",
+                    "provider_name": "quickshift",
+                },
+            },
+            traits={"ip_address": "5.6.7.8"},
+        )
+        self.assertIsNone(model.anonymizer.confidence)
+        self.assertIsNone(model.anonymizer.provider_name)
+        self.assertFalse(model.anonymizer.is_anonymous)
+        self.assertEqual(model.anonymizer.residential.confidence, 82)
+        self.assertEqual(
+            model.anonymizer.residential.network_last_seen,
+            datetime.date(2026, 5, 11),
+        )
+        self.assertEqual(model.anonymizer.residential.provider_name, "quickshift")
 
     def test_city_full(self) -> None:
         raw = {