Add support for the Anonymous Plus database

Author: oschwald

HISTORY.rst

@@ -4,6 +4,13 @@
 History
 -------
 
+5.1.0
+++++++++++++++++++
+
+* Support for the GeoIP Anonymous Plus database has been added. To do a lookup
+  in this database, use the ``anonymous_plus`` method on ``Reader``.
+
+
 5.0.1 (2025-01-28)
 ++++++++++++++++++
 

README.rst

@@ -268,6 +268,42 @@ Anonymous IP Database
     >>>     response.network
     IPv4Network('203.0.113.0/24')
 
+Anonymous Plus Database
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: pycon
+
+    >>> import geoip2.database
+    >>>
+    >>> # This creates a Reader object. You should use the same object
+    >>> # across multiple requests as creation of it is expensive.
+    >>> with geoip2.database.Reader('/path/to/GeoIP-Anonymous-Plus.mmdb') as reader:
+    >>>
+    >>>     response = reader.anonymous_plus('203.0.113.0')
+    >>>
+    >>>     response.anonymizer_confidence
+    30
+    >>>     response.is_anonymous
+    True
+    >>>     response.is_anonymous_vpn
+    True
+    >>>     response.is_hosting_provider
+    False
+    >>>     response.is_public_proxy
+    False
+    >>>     response.is_residential_proxy
+    False
+    >>>     response.is_tor_exit_node
+    False
+    >>>     response.ip_address
+    '203.0.113.0'
+    >>>     response.network
+    IPv4Network('203.0.113.0/24')
+    >>>     response.network_last_seen
+    datetime.date(2025, 4, 18)
+    >>>     response.provider_name
+    FooBar VPNs
+
 ASN Database
 ^^^^^^^^^^^^
 

geoip2/database.py

@@ -27,6 +27,7 @@
     ASN,
     ISP,
     AnonymousIP,
+    AnonymousPlus,
     City,
     ConnectionType,
     Country,
@@ -167,6 +168,23 @@ def anonymous_ip(self, ip_address: IPAddress) -> AnonymousIP:
             ),
         )
 
+    def anonymous_plus(self, ip_address: IPAddress) -> AnonymousPlus:
+        """Get the AnonymousPlus object for the IP address.
+
+        :param ip_address: IPv4 or IPv6 address as a string.
+
+        :returns: :py:class:`geoip2.models.AnonymousPlus` object
+
+        """
+        return cast(
+            AnonymousPlus,
+            self._flat_model_for(
+                geoip2.models.AnonymousPlus,
+                "GeoIP-Anonymous-Plus",
+                ip_address,
+            ),
+        )
+
     def asn(self, ip_address: IPAddress) -> ASN:
         """Get the ASN object for the IP address.
 

geoip2/models.py

@@ -12,11 +12,12 @@
 """
 
 # pylint: disable=too-many-instance-attributes,too-few-public-methods,too-many-arguments
+import datetime
 import ipaddress
 from abc import ABCMeta
 from collections.abc import Sequence
-from typing import Optional, Union
 from ipaddress import IPv4Address, IPv6Address
+from typing import Optional, Union
 
 import geoip2.records
 from geoip2._internal import Model
@@ -512,6 +513,128 @@ def __init__(
         self.is_tor_exit_node = is_tor_exit_node
 
 
+class AnonymousPlus(AnonymousIP):
+    """Model class for the GeoIP Anonymous Plus.
+
+    This class provides the following attribute:
+
+    .. attribute: anonymizer_confidence
+
+      A score ranging from 1 to 99 that is our percent confidence that the
+      network is currently part of an actively used VPN service.
+
+      :type: str
+
+    .. attribute:: is_anonymous
+
+      This is true if the IP address belongs to any sort of anonymous network.
+
+      :type: bool
+
+    .. attribute:: is_anonymous_vpn
+
+      This is true if the IP address is registered to an anonymous VPN
+      provider.
+
+      If a VPN provider does not register subnets under names associated with
+      them, we will likely only flag their IP ranges using the
+      ``is_hosting_provider`` attribute.
+
+      :type: bool
+
+    .. attribute:: is_hosting_provider
+
+      This is true if the IP address belongs to a hosting or VPN provider
+      (see description of ``is_anonymous_vpn`` attribute).
+
+      :type: bool
+
+    .. attribute:: is_public_proxy
+
+      This is true if the IP address belongs to a public proxy.
+
+      :type: bool
+
+    .. attribute:: is_residential_proxy
+
+      This is true if the IP address is on a suspected anonymizing network
+      and belongs to a residential ISP.
+
+      :type: bool
+
+    .. attribute:: is_tor_exit_node
+
+      This is true if the IP address is a Tor exit node.
+
+      :type: bool
+
+    .. attribute:: ip_address
+
+      The IP address used in the lookup.
+
+      :type: ipaddress.IPv4Address or ipaddress.IPv6Address
+
+    .. attribute:: network
+
+      The network associated with the record. In particular, this is the
+      largest network where all of the fields besides ip_address have the same
+      value.
+
+      :type: ipaddress.IPv4Network or ipaddress.IPv6Network
+
+    .. attribute:: network_last_seen
+
+      The last day that the network was sighted in our analysis of anonymized
+      networks.
+
+      :type: str
+
+    .. attribute:: provider_name
+
+      The name of the VPN provider (e.g., NordVPN, SurfShark, etc.) associated
+      with the network.
+
+      :type: str
+    """
+
+    anonymizer_confidence: Optional[int]
+    network_last_seen: Optional[datetime.date]
+    provider_name: Optional[str]
+
+    def __init__(
+        self,
+        ip_address: IPAddress,
+        *,
+        anonymizer_confidence: Optional[int] = None,
+        is_anonymous: bool = False,
+        is_anonymous_vpn: bool = False,
+        is_hosting_provider: bool = False,
+        is_public_proxy: bool = False,
+        is_residential_proxy: bool = False,
+        is_tor_exit_node: bool = False,
+        network: Optional[str] = None,
+        network_last_seen: Optional[str] = None,
+        prefix_len: Optional[int] = None,
+        provider_name: Optional[str] = None,
+        **_,
+    ) -> None:
+        super().__init__(
+            is_anonymous=is_anonymous,
+            is_anonymous_vpn=is_anonymous_vpn,
+            is_hosting_provider=is_hosting_provider,
+            is_public_proxy=is_public_proxy,
+            is_residential_proxy=is_residential_proxy,
+            is_tor_exit_node=is_tor_exit_node,
+            ip_address=ip_address,
+            network=network,
+            prefix_len=prefix_len,
+        )
+        self.anonymizer_confidence = anonymizer_confidence
+        if network_last_seen is not None:
+            self.network_last_seen = datetime.date.fromisoformat(network_last_seen)
+        self.provider_name = provider_name
+
+
 class ASN(SimpleModel):
     """Model class for the GeoLite2 ASN.
 

tests/data

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 
 
+import datetime
 import ipaddress
 import sys
 import unittest
@@ -86,6 +87,27 @@ def test_anonymous_ip(self) -> None:
         self.assertEqual(record.network, ipaddress.ip_network("1.2.0.0/16"))
         reader.close()
 
+    def test_anonymous_plus(self) -> None:
+        with geoip2.database.Reader(
+            "tests/data/test-data/GeoIP-Anonymous-Plus-Test.mmdb",
+        ) as reader:
+
+            ip_address = "1.2.0.1"
+
+            record = reader.anonymous_plus(ip_address)
+
+            self.assertEqual(record.anonymizer_confidence, 30)
+            self.assertEqual(record.is_anonymous, True)
+            self.assertEqual(record.is_anonymous_vpn, True)
+            self.assertEqual(record.is_hosting_provider, False)
+            self.assertEqual(record.is_public_proxy, False)
+            self.assertEqual(record.is_residential_proxy, False)
+            self.assertEqual(record.is_tor_exit_node, False)
+            self.assertEqual(record.ip_address, ipaddress.ip_address(ip_address))
+            self.assertEqual(record.network, ipaddress.ip_network("1.2.0.1/32"))
+            self.assertEqual(record.network_last_seen, datetime.date(2025, 4, 14))
+            self.assertEqual(record.provider_name, "foo")
+
     def test_anonymous_ip_all_set(self) -> None:
         reader = geoip2.database.Reader(
             "tests/data/test-data/GeoIP2-Anonymous-IP-Test.mmdb",