Add support for new anonymizer and IP risk outputs

oschwald · claude · oschwald · commit 9610eca1e0e5 · 2025-11-06T12:50:05.000-08:00
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>
diff --git a/CHANGELOG.md b/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
diff --git a/src/main/java/com/maxmind/geoip2/JsonSerializable.java b/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)
diff --git a/src/main/java/com/maxmind/geoip2/WebServiceClient.java b/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;
diff --git a/src/main/java/com/maxmind/geoip2/model/InsightsResponse.java b/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;
@@ -39,6 +40,9 @@
  *                     to most specific (smallest). If the response did not contain any
  *                     subdivisions, this is an empty list.
  * @param traits Record for the traits of the requested IP address.
+ * @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.
  * @see <a href="https://dev.maxmind.com/geoip/docs/web-services?lang=en">GeoIP2 Web
  * Services</a>
  */
@@ -71,7 +75,10 @@ public record InsightsResponse(
     List<Subdivision> subdivisions,
 
     @JsonProperty("traits")
-    Traits traits
+    Traits traits,
+
+    @JsonProperty("anonymizer")
+    Anonymizer anonymizer
 ) implements JsonSerializable {
 
     /**
@@ -89,6 +96,7 @@ public record InsightsResponse(
             ? representedCountry : new RepresentedCountry();
         subdivisions = subdivisions != null ? List.copyOf(subdivisions) : List.of();
         traits = traits != null ? traits : new Traits();
+        anonymizer = anonymizer != null ? anonymizer : new Anonymizer();
     }
 
     /**
diff --git a/src/main/java/com/maxmind/geoip2/record/Anonymizer.java b/src/main/java/com/maxmind/geoip2/record/Anonymizer.java
@@ -0,0 +1,123 @@
+package com.maxmind.geoip2.record;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.maxmind.db.MaxMindDbConstructor;
+import com.maxmind.db.MaxMindDbParameter;
+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")
+    @MaxMindDbParameter(name = "confidence")
+    Integer confidence,
+
+    @JsonProperty("is_anonymous")
+    @MaxMindDbParameter(name = "is_anonymous", useDefault = true)
+    boolean isAnonymous,
+
+    @JsonProperty("is_anonymous_vpn")
+    @MaxMindDbParameter(name = "is_anonymous_vpn", useDefault = true)
+    boolean isAnonymousVpn,
+
+    @JsonProperty("is_hosting_provider")
+    @MaxMindDbParameter(name = "is_hosting_provider", useDefault = true)
+    boolean isHostingProvider,
+
+    @JsonProperty("is_public_proxy")
+    @MaxMindDbParameter(name = "is_public_proxy", useDefault = true)
+    boolean isPublicProxy,
+
+    @JsonProperty("is_residential_proxy")
+    @MaxMindDbParameter(name = "is_residential_proxy", useDefault = true)
+    boolean isResidentialProxy,
+
+    @JsonProperty("is_tor_exit_node")
+    @MaxMindDbParameter(name = "is_tor_exit_node", useDefault = true)
+    boolean isTorExitNode,
+
+    @JsonProperty("network_last_seen")
+    @MaxMindDbParameter(name = "network_last_seen")
+    LocalDate networkLastSeen,
+
+    @JsonProperty("provider_name")
+    @MaxMindDbParameter(name = "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, (LocalDate) null, null);
+    }
+
+    /**
+     * Constructs an instance of {@code Anonymizer} with date parsing from MaxMind database.
+     *
+     * @param confidence         confidence that the network is a VPN
+     * @param isAnonymous        whether the IP address belongs to any sort of anonymous network
+     * @param isAnonymousVpn     whether the IP address belongs to an anonymous VPN system
+     * @param isHostingProvider  whether the IP address belongs to a hosting provider
+     * @param isPublicProxy      whether the IP address belongs to a public proxy system
+     * @param isResidentialProxy whether the IP address belongs to a residential proxy system
+     * @param isTorExitNode      whether the IP address is a Tor exit node
+     * @param networkLastSeen    the last sighting of the network
+     * @param providerName       the name of the VPN provider
+     */
+    @MaxMindDbConstructor
+    public Anonymizer(
+        @MaxMindDbParameter(name = "confidence") Integer confidence,
+        @MaxMindDbParameter(name = "is_anonymous", useDefault = true) boolean isAnonymous,
+        @MaxMindDbParameter(name = "is_anonymous_vpn", useDefault = true) boolean isAnonymousVpn,
+        @MaxMindDbParameter(name = "is_hosting_provider", useDefault = true)
+        boolean isHostingProvider,
+        @MaxMindDbParameter(name = "is_public_proxy", useDefault = true) boolean isPublicProxy,
+        @MaxMindDbParameter(name = "is_residential_proxy", useDefault = true)
+        boolean isResidentialProxy,
+        @MaxMindDbParameter(name = "is_tor_exit_node", useDefault = true)
+        boolean isTorExitNode,
+        @MaxMindDbParameter(name = "network_last_seen") String networkLastSeen,
+        @MaxMindDbParameter(name = "provider_name") String providerName
+    ) {
+        this(
+            confidence,
+            isAnonymous,
+            isAnonymousVpn,
+            isHostingProvider,
+            isPublicProxy,
+            isResidentialProxy,
+            isTorExitNode,
+            networkLastSeen != null ? LocalDate.parse(networkLastSeen) : null,
+            providerName
+        );
+    }
+}
diff --git a/src/main/java/com/maxmind/geoip2/record/Traits.java b/src/main/java/com/maxmind/geoip2/record/Traits.java
@@ -37,14 +37,26 @@
  *                  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 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">
@@ -72,6 +84,9 @@
  * @param staticIpScore The static IP score of the IP address. This is an indicator of how static
  *                      or dynamic an IP address is. This is only available from the Insights web
  *                      service.
+ * @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.
  */
 public record Traits(
     @JsonProperty("autonomous_system_number")
@@ -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,14 +132,17 @@ 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,
@@ -158,7 +179,11 @@ public record Traits(
 
     @JsonProperty("static_ip_score")
     @MaxMindDbParameter(name = "static_ip_score")
-    Double staticIpScore
+    Double staticIpScore,
+
+    @JsonProperty("ip_risk_snapshot")
+    @MaxMindDbParameter(name = "ip_risk_snapshot")
+    Double ipRiskSnapshot
 ) implements JsonSerializable {
 
     /**
@@ -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);
     }
 
     /**
diff --git a/src/test/java/com/maxmind/geoip2/model/InsightsResponseTest.java b/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
diff --git a/src/test/java/com/maxmind/geoip2/model/JsonTest.java b/src/test/java/com/maxmind/geoip2/model/JsonTest.java
diff --git a/src/test/resources/test-data/insights0.json b/src/test/resources/test-data/insights0.json
diff --git a/src/test/resources/test-data/insights1.json b/src/test/resources/test-data/insights1.json
