Add support for new anonymizer and IP risk outputs

Adds Anonymizer record to InsightsResponse with VPN confidence, network last seen, and provider name fields. Adds ipRiskSnapshot field to Traits for static IP risk scores. Deprecates anonymous IP flags in Traits in favor of the new Anonymizer record for Insights responses.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: oschwald

CHANGELOG.md

@@ -18,6 +18,20 @@ CHANGELOG
   field.
 * The deprecation notices for IP Risk database support have been removed.
   IP Risk database support will continue to be maintained.
+* A new `Anonymizer` record has been added to the `InsightsResponse` model. This
+  record consolidates anonymizer information including VPN confidence scores,
+  network last seen dates, and provider names. It includes the following fields:
+  `confidence`, `isAnonymous`, `isAnonymousVpn`, `isHostingProvider`,
+  `isPublicProxy`, `isResidentialProxy`, `isTorExitNode`, `networkLastSeen`, and
+  `providerName`.
+* A new `ipRiskSnapshot` field has been added to the `Traits` record. This field
+  provides a static risk score (ranging from 0.01 to 99) associated with the IP
+  address. This is available from the GeoIP2 Precision Insights web service.
+* The anonymous IP flags in the `Traits` record (`isAnonymous`, `isAnonymousVpn`,
+  `isHostingProvider`, `isPublicProxy`, `isResidentialProxy`, and `isTorExitNode`)
+  have been deprecated in favor of using the new `Anonymizer` record in the
+  `InsightsResponse`. These fields will continue to work but will be removed in
+  version 6.0.0.
 * **BREAKING:** The deprecated `WebServiceClient.Builder` methods
   `connectTimeout(int)`, `readTimeout(int)`, and `proxy(Proxy)` have been
   removed. Use `connectTimeout(Duration)`, `requestTimeout(Duration)`, and

src/main/java/com/maxmind/geoip2/JsonSerializable.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.databind.MapperFeature;
+import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import java.io.IOException;
@@ -20,6 +21,7 @@ public interface JsonSerializable {
     default String toJson() throws IOException {
         JsonMapper mapper = JsonMapper.builder()
             .disable(MapperFeature.CAN_OVERRIDE_ACCESS_MODIFIERS)
+            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
             .addModule(new JavaTimeModule())
             .addModule(new InetAddressModule())
             .serializationInclusion(JsonInclude.Include.NON_NULL)

src/main/java/com/maxmind/geoip2/WebServiceClient.java

@@ -5,7 +5,9 @@
 import com.fasterxml.jackson.databind.InjectableValues;
 import com.fasterxml.jackson.databind.MapperFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.databind.json.JsonMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import com.maxmind.geoip2.exception.AddressNotFoundException;
 import com.maxmind.geoip2.exception.AuthenticationException;
 import com.maxmind.geoip2.exception.GeoIp2Exception;
@@ -133,6 +135,8 @@ private WebServiceClient(Builder builder) {
         mapper = JsonMapper.builder()
             .disable(MapperFeature.CAN_OVERRIDE_ACCESS_MODIFIERS)
             .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+            .addModule(new JavaTimeModule())
             .build();
 
         requestTimeout = builder.requestTimeout;

src/main/java/com/maxmind/geoip2/model/InsightsResponse.java

@@ -3,6 +3,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.maxmind.geoip2.JsonSerializable;
+import com.maxmind.geoip2.record.Anonymizer;
 import com.maxmind.geoip2.record.City;
 import com.maxmind.geoip2.record.Continent;
 import com.maxmind.geoip2.record.Country;
@@ -19,6 +20,9 @@
  * This class provides a model for the data returned by the Insights web
  * service.
  *
+ * @param anonymizer Anonymizer record for the requested IP address. This contains information
+ *                   about whether the IP address belongs to an anonymizing network such as a VPN,
+ *                   proxy, or Tor exit node.
  * @param city City record for the requested IP address.
  * @param continent Continent record for the requested IP address.
  * @param country Country record for the requested IP address. This object represents the country
@@ -43,6 +47,9 @@
  * Services</a>
  */
 public record InsightsResponse(
+    @JsonProperty("anonymizer")
+    Anonymizer anonymizer,
+
     @JsonProperty("city")
     City city,
 
@@ -78,6 +85,7 @@ public record InsightsResponse(
      * Compact canonical constructor that sets defaults for null values.
      */
     public InsightsResponse {
+        anonymizer = anonymizer != null ? anonymizer : new Anonymizer();
         city = city != null ? city : new City();
         continent = continent != null ? continent : new Continent();
         country = country != null ? country : new Country();

src/main/java/com/maxmind/geoip2/record/Anonymizer.java

@@ -0,0 +1,71 @@
+package com.maxmind.geoip2.record;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.maxmind.geoip2.JsonSerializable;
+import java.time.LocalDate;
+
+/**
+ * <p>
+ * Contains data for the anonymizer record associated with an IP address.
+ * </p>
+ * <p>
+ * This record is returned by the GeoIP2 Precision Insights web service.
+ * </p>
+ *
+ * @param 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. This is only
+ *                   available from the GeoIP2 Precision Insights web service.
+ * @param isAnonymous Whether the IP address belongs to any sort of anonymous network.
+ * @param isAnonymousVpn Whether 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 isHostingProvider.
+ * @param isHostingProvider Whether the IP address belongs to a hosting or VPN provider (see
+ *                          description of isAnonymousVpn).
+ * @param isPublicProxy Whether the IP address belongs to a public proxy.
+ * @param isResidentialProxy Whether the IP address is on a suspected anonymizing network and
+ *                           belongs to a residential ISP.
+ * @param isTorExitNode Whether the IP address is a Tor exit node.
+ * @param networkLastSeen The last day that the network was sighted in our analysis of anonymized
+ *                        networks. This is only available from the GeoIP2 Precision Insights web
+ *                        service.
+ * @param providerName The name of the VPN provider (e.g., NordVPN, SurfShark, etc.) associated
+ *                     with the network. This is only available from the GeoIP2 Precision Insights
+ *                     web service.
+ */
+public record Anonymizer(
+    @JsonProperty("confidence")
+    Integer confidence,
+
+    @JsonProperty("is_anonymous")
+    boolean isAnonymous,
+
+    @JsonProperty("is_anonymous_vpn")
+    boolean isAnonymousVpn,
+
+    @JsonProperty("is_hosting_provider")
+    boolean isHostingProvider,
+
+    @JsonProperty("is_public_proxy")
+    boolean isPublicProxy,
+
+    @JsonProperty("is_residential_proxy")
+    boolean isResidentialProxy,
+
+    @JsonProperty("is_tor_exit_node")
+    boolean isTorExitNode,
+
+    @JsonProperty("network_last_seen")
+    LocalDate networkLastSeen,
+
+    @JsonProperty("provider_name")
+    String providerName
+) implements JsonSerializable {
+
+    /**
+     * Constructs an {@code Anonymizer} record with {@code null} values for all the nullable
+     * fields and {@code false} for all boolean fields.
+     */
+    public Anonymizer() {
+        this(null, false, false, false, false, false, false, null, null);
+    }
+}

src/main/java/com/maxmind/geoip2/record/Traits.java

@@ -37,14 +37,29 @@
  *                  address for the system the code is running on. If the system is behind a
  *                  NAT, this may differ from the IP address locally assigned to it.
  * @param isAnonymous This is true if the IP address belongs to any sort of anonymous network.
+ *                    This field is deprecated. Please use the anonymizer object from the
+ *                    Insights response.
  * @param isAnonymousVpn This is true if the IP address belongs to an anonymous VPN system.
+ *                       This field is deprecated. Please use the anonymizer object from the
+ *                       Insights response.
  * @param isAnycast This is true if the IP address is an anycast address.
  * @param isHostingProvider This is true if the IP address belongs to a hosting provider.
+ *                          This field is deprecated. Please use the anonymizer object from the
+ *                          Insights response.
  * @param isLegitimateProxy This is true if the IP address belongs to a legitimate proxy.
  * @param isPublicProxy This is true if the IP address belongs to a public proxy.
+ *                      This field is deprecated. Please use the anonymizer object from the
+ *                      Insights response.
  * @param isResidentialProxy This is true if the IP address is on a suspected anonymizing network
  *                           and belongs to a residential ISP.
+ *                           This field is deprecated. Please use the anonymizer object from the
+ *                           Insights response.
  * @param isTorExitNode This is true if the IP address is a Tor exit node.
+ *                      This field is deprecated. Please use the anonymizer object from the
+ *                      Insights response.
+ * @param ipRiskSnapshot The risk score associated with the IP address. This is a static score
+ *                       ranging from 0.01 to 99 indicating the risk associated with the IP address.
+ *                       This is only available from the Insights web service.
  * @param isp The name of the ISP associated with the IP address. This is only available from
  *            the City Plus and Insights web services and the Enterprise database.
  * @param mobileCountryCode The <a href="https://en.wikipedia.org/wiki/Mobile_country_code">
@@ -94,10 +109,12 @@ public record Traits(
     @MaxMindDbIpAddress
     InetAddress ipAddress,
 
+    @Deprecated(since = "5.0.0", forRemoval = true)
     @JsonProperty("is_anonymous")
     @MaxMindDbParameter(name = "is_anonymous", useDefault = true)
     boolean isAnonymous,
 
+    @Deprecated(since = "5.0.0", forRemoval = true)
     @JsonProperty("is_anonymous_vpn")
     @MaxMindDbParameter(name = "is_anonymous_vpn", useDefault = true)
     boolean isAnonymousVpn,
@@ -106,6 +123,7 @@ public record Traits(
     @MaxMindDbParameter(name = "is_anycast", useDefault = true)
     boolean isAnycast,
 
+    @Deprecated(since = "5.0.0", forRemoval = true)
     @JsonProperty("is_hosting_provider")
     @MaxMindDbParameter(name = "is_hosting_provider", useDefault = true)
     boolean isHostingProvider,
@@ -114,18 +132,25 @@ public record Traits(
     @MaxMindDbParameter(name = "is_legitimate_proxy", useDefault = true)
     boolean isLegitimateProxy,
 
+    @Deprecated(since = "5.0.0", forRemoval = true)
     @JsonProperty("is_public_proxy")
     @MaxMindDbParameter(name = "is_public_proxy", useDefault = true)
     boolean isPublicProxy,
 
+    @Deprecated(since = "5.0.0", forRemoval = true)
     @JsonProperty("is_residential_proxy")
     @MaxMindDbParameter(name = "is_residential_proxy", useDefault = true)
     boolean isResidentialProxy,
 
+    @Deprecated(since = "5.0.0", forRemoval = true)
     @JsonProperty("is_tor_exit_node")
     @MaxMindDbParameter(name = "is_tor_exit_node", useDefault = true)
     boolean isTorExitNode,
 
+    @JsonProperty("ip_risk_snapshot")
+    @MaxMindDbParameter(name = "ip_risk_snapshot")
+    Double ipRiskSnapshot,
+
     @JsonProperty("isp")
     @MaxMindDbParameter(name = "isp")
     String isp,
@@ -168,7 +193,7 @@ public Traits() {
         this(null, null, (ConnectionType) null, null,
             null, false, false, false, false,
             false, false, false, false, null,
-            null, null, null, null, null, null, null);
+            null, null, null, null, null, null, null, null);
     }
 
     /**

src/test/java/com/maxmind/geoip2/model/InsightsResponseTest.java

@@ -15,6 +15,7 @@
 import com.maxmind.geoip2.WebServiceClient;
 import com.maxmind.geoip2.exception.GeoIp2Exception;
 import com.maxmind.geoip2.model.ConnectionTypeResponse.ConnectionType;
+import com.maxmind.geoip2.record.Anonymizer;
 import com.maxmind.geoip2.record.Location;
 import com.maxmind.geoip2.record.MaxMind;
 import com.maxmind.geoip2.record.Postal;
@@ -23,6 +24,7 @@
 import java.io.IOException;
 import java.net.InetAddress;
 import java.net.URISyntaxException;
+import java.time.LocalDate;
 import java.util.List;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -168,6 +170,42 @@ public void testTraits() {
             traits.userCount(),
             "traits.userCount() does not return 2"
         );
+        assertEquals(
+            Double.valueOf(0.01),
+            traits.ipRiskSnapshot(),
+            "traits.ipRiskSnapshot() does not return 0.01"
+        );
+    }
+
+    @Test
+    public void testAnonymizer() {
+        Anonymizer anonymizer = this.insights.anonymizer();
+
+        assertNotNull(anonymizer, "insights.anonymizer() returns null");
+        assertEquals(
+            Integer.valueOf(99),
+            anonymizer.confidence(),
+            "anonymizer.confidence() does not return 99"
+        );
+        assertTrue(anonymizer.isAnonymous(), "anonymizer.isAnonymous() returns true");
+        assertTrue(anonymizer.isAnonymousVpn(), "anonymizer.isAnonymousVpn() returns true");
+        assertTrue(anonymizer.isHostingProvider(), "anonymizer.isHostingProvider() returns true");
+        assertTrue(anonymizer.isPublicProxy(), "anonymizer.isPublicProxy() returns true");
+        assertTrue(
+            anonymizer.isResidentialProxy(),
+            "anonymizer.isResidentialProxy() returns true"
+        );
+        assertTrue(anonymizer.isTorExitNode(), "anonymizer.isTorExitNode() returns true");
+        assertEquals(
+            LocalDate.parse("2024-12-31"),
+            anonymizer.networkLastSeen(),
+            "anonymizer.networkLastSeen() does not return 2024-12-31"
+        );
+        assertEquals(
+            "NordVPN",
+            anonymizer.providerName(),
+            "anonymizer.providerName() does not return NordVPN"
+        );
     }
 
     @Test

src/test/java/com/maxmind/geoip2/model/JsonTest.java

@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.InjectableValues;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.MapperFeature;
+import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import com.fasterxml.jackson.jr.ob.JSON;
 import java.io.IOException;
@@ -46,10 +47,22 @@ public void testInsightsSerialization() throws IOException {
             .put("network", "1.2.3.0/24")
             .put("organization", "Blorg")
             .put("user_type", "college")
+            .put("ip_risk_snapshot", 0.01)
             // This is here just to simplify the testing. We expect the
             // difference
             .put("is_legitimate_proxy", false)
             .end()
+            .startObjectField("anonymizer")
+            .put("confidence", 99)
+            .put("is_anonymous", true)
+            .put("is_anonymous_vpn", true)
+            .put("is_hosting_provider", true)
+            .put("is_public_proxy", true)
+            .put("is_residential_proxy", true)
+            .put("is_tor_exit_node", true)
+            .put("network_last_seen", "2024-12-31")
+            .put("provider_name", "NordVPN")
+            .end()
             .startObjectField("country")
             .startObjectField("names")
             .put("en", "United States of America")
@@ -334,6 +347,8 @@ public void testIspSerialization() throws Exception {
         throws IOException {
         JsonMapper mapper = JsonMapper.builder()
             .disable(MapperFeature.CAN_OVERRIDE_ACCESS_MODIFIERS)
+            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+            .addModule(new com.fasterxml.jackson.datatype.jsr310.JavaTimeModule())
             .addModule(new com.maxmind.geoip2.InetAddressModule())
             .build();
         InjectableValues inject = new InjectableValues.Std().addValue(

src/test/resources/test-data/insights0.json

@@ -82,6 +82,18 @@
     "organization": "Blorg",
     "static_ip_score": 1.3,
     "user_count": 2,
-    "user_type": "college"
+    "user_type": "college",
+    "ip_risk_snapshot": 0.01
+  },
+  "anonymizer": {
+    "confidence": 99,
+    "is_anonymous": true,
+    "is_anonymous_vpn": true,
+    "is_hosting_provider": true,
+    "is_public_proxy": true,
+    "is_residential_proxy": true,
+    "is_tor_exit_node": true,
+    "network_last_seen": "2024-12-31",
+    "provider_name": "NordVPN"
   }
 }

src/test/resources/test-data/insights1.json

@@ -98,6 +98,18 @@
     "organization": "Blorg",
     "static_ip_score": 1.3,
     "user_count": 2,
-    "user_type": "college"
+    "user_type": "college",
+    "ip_risk_snapshot": 0.01
+  },
+  "anonymizer": {
+    "confidence": 99,
+    "is_anonymous": true,
+    "is_anonymous_vpn": true,
+    "is_hosting_provider": true,
+    "is_public_proxy": true,
+    "is_residential_proxy": true,
+    "is_tor_exit_node": true,
+    "network_last_seen": "2024-12-31",
+    "provider_name": "NordVPN"
   }
 }