Skip to content

Commit 341119e

Browse files
oschwaldclaude
oschwald
and
claude
committed
Add anonymizer and IP risk data to Insights web service
This commit adds support for the new anonymizer object and IP risk snapshot field in the GeoIP2 Insights web service response. Key changes: - Add new Anonymizer record class with VPN detection fields (confidence, provider name, network last seen, and anonymity flags) - Add anonymizer property to Insights model - Add ipRiskSnapshot field to Traits record for static IP risk scoring - Deprecate anonymous IP flags in Traits (isAnonymous, isAnonymousVpn, isHostingProvider, isPublicProxy, isResidentialProxy, isTorExitNode) in favor of the new anonymizer object - Update tests to cover new fields - Update CHANGELOG for version 3.3.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 144d04e commit 341119e

File tree

5 files changed

+297
-2
lines changed

5 files changed

+297
-2
lines changed

‎CHANGELOG.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,25 @@
11
CHANGELOG
22
=========
33

4+
3.3.0 (unreleased)
5+
------------------
6+
7+
* A new `anonymizer` property has been added to `GeoIp2\Model\Insights`.
8+
This property is an instance of `GeoIp2\Record\Anonymizer` and provides
9+
information about whether the IP address belongs to an anonymous network,
10+
VPN provider details (including `confidence`, `providerName`, and
11+
`networkLastSeen`), and various anonymity flags. This data is available
12+
from the GeoIP2 Insights web service.
13+
* A new `ipRiskSnapshot` property has been added to `GeoIp2\Record\Traits`.
14+
This property provides a risk score from 0.01 to 99.99 indicating the risk
15+
associated with the IP address. Higher values indicate higher risk. This is
16+
a static snapshot that is less dynamic than minFraud risk scoring. This
17+
attribute is only available from the GeoIP2 Insights web service.
18+
* The `isAnonymous`, `isAnonymousVpn`, `isHostingProvider`, `isPublicProxy`,
19+
`isResidentialProxy`, and `isTorExitNode` properties in
20+
`GeoIp2\Record\Traits` have been deprecated. Please use the corresponding
21+
properties in the new `anonymizer` object in the Insights response instead.
22+
423
3.2.0 (2025-05-05)
524
------------------
625

‎src/Model/Insights.php‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,48 @@
44

55
namespace GeoIp2\Model;
66

7+
use GeoIp2\Record\Anonymizer;
8+
79
/**
810
* Model class for the data returned by GeoIP2 Insights web service.
911
*
1012
* See https://dev.maxmind.com/geoip/docs/web-services?lang=en for
1113
* more details.
1214
*/
13-
// phpcs:disable
14-
class Insights extends City {}
15+
class Insights extends City
16+
{
17+
/**
18+
* @var Anonymizer Anonymizer data for the requested IP address. This
19+
* includes information about whether the IP belongs to an anonymous
20+
* network, VPN provider details, and confidence scores.
21+
*/
22+
public readonly Anonymizer $anonymizer;
23+
24+
/**
25+
* @ignore
26+
*
27+
* @param array<string, mixed> $raw
28+
* @param list<string> $locales
29+
*/
30+
public function __construct(array $raw, array $locales = ['en'])
31+
{
32+
parent::__construct($raw, $locales);
33+
34+
$this->anonymizer = new Anonymizer($raw['anonymizer'] ?? []);
35+
}
36+
37+
/**
38+
* @return array<string, mixed>|null
39+
*/
40+
public function jsonSerialize(): ?array
41+
{
42+
$js = parent::jsonSerialize();
43+
44+
$anonymizer = $this->anonymizer->jsonSerialize();
45+
if (!empty($anonymizer)) {
46+
$js['anonymizer'] = $anonymizer;
47+
}
48+
49+
return $js;
50+
}
51+
}

‎src/Record/Anonymizer.php‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace GeoIp2\Record;
6+
7+
/**
8+
* Contains data for the anonymizer record associated with an IP address.
9+
*
10+
* This record is returned by the GeoIP2 Insights web service.
11+
*/
12+
class Anonymizer implements \JsonSerializable
13+
{
14+
/**
15+
* @var int|null A confidence score from 1-99 indicating our confidence that the IP
16+
* address is a VPN. Currently, this is either 30 or 99. This attribute is
17+
* only available from the GeoIP2 Insights web service.
18+
*/
19+
public readonly ?int $confidence;
20+
21+
/**
22+
* @var bool This is true if the IP address belongs to any sort of anonymous network.
23+
* This attribute is only available from the GeoIP2 Insights web service.
24+
*/
25+
public readonly bool $isAnonymous;
26+
27+
/**
28+
* @var bool This is true if the IP address is registered to an anonymous VPN provider.
29+
* If a VPN provider does not register subnets under names associated with them,
30+
* we will likely only flag their IP ranges using the isHostingProvider property.
31+
* This attribute is only available from the GeoIP2 Insights web service.
32+
*/
33+
public readonly bool $isAnonymousVpn;
34+
35+
/**
36+
* @var bool This is true if the IP address belongs to a hosting or VPN provider (see
37+
* description of isAnonymousVpn property). This attribute is only available from
38+
* the GeoIP2 Insights web service.
39+
*/
40+
public readonly bool $isHostingProvider;
41+
42+
/**
43+
* @var bool This is true if the IP address belongs to a public proxy. This attribute
44+
* is only available from the GeoIP2 Insights web service.
45+
*/
46+
public readonly bool $isPublicProxy;
47+
48+
/**
49+
* @var bool This is true if the IP address is on a suspected anonymizing network and
50+
* belongs to a residential ISP. This attribute is only available from the GeoIP2
51+
* Insights web service.
52+
*/
53+
public readonly bool $isResidentialProxy;
54+
55+
/**
56+
* @var bool This is true if the IP address is a Tor exit node. This attribute is only
57+
* available from the GeoIP2 Insights web service.
58+
*/
59+
public readonly bool $isTorExitNode;
60+
61+
/**
62+
* @var string|null The date the anonymizer network was last seen in YYYY-MM-DD format.
63+
* This attribute is only available from the GeoIP2 Insights web service.
64+
*/
65+
public readonly ?string $networkLastSeen;
66+
67+
/**
68+
* @var string|null The name of the VPN provider, for example, NordVPN or SurfShark.
69+
* This attribute is only available from the GeoIP2 Insights web service.
70+
*/
71+
public readonly ?string $providerName;
72+
73+
/**
74+
* @ignore
75+
*
76+
* @param array<string, mixed> $record
77+
*/
78+
public function __construct(array $record)
79+
{
80+
$this->confidence = $record['confidence'] ?? null;
81+
$this->isAnonymous = $record['is_anonymous'] ?? false;
82+
$this->isAnonymousVpn = $record['is_anonymous_vpn'] ?? false;
83+
$this->isHostingProvider = $record['is_hosting_provider'] ?? false;
84+
$this->isPublicProxy = $record['is_public_proxy'] ?? false;
85+
$this->isResidentialProxy = $record['is_residential_proxy'] ?? false;
86+
$this->isTorExitNode = $record['is_tor_exit_node'] ?? false;
87+
$this->networkLastSeen = $record['network_last_seen'] ?? null;
88+
$this->providerName = $record['provider_name'] ?? null;
89+
}
90+
91+
/**
92+
* @return array<string, mixed>
93+
*/
94+
public function jsonSerialize(): array
95+
{
96+
$js = [];
97+
98+
if ($this->confidence !== null) {
99+
$js['confidence'] = $this->confidence;
100+
}
101+
if ($this->isAnonymous !== false) {
102+
$js['is_anonymous'] = $this->isAnonymous;
103+
}
104+
if ($this->isAnonymousVpn !== false) {
105+
$js['is_anonymous_vpn'] = $this->isAnonymousVpn;
106+
}
107+
if ($this->isHostingProvider !== false) {
108+
$js['is_hosting_provider'] = $this->isHostingProvider;
109+
}
110+
if ($this->isPublicProxy !== false) {
111+
$js['is_public_proxy'] = $this->isPublicProxy;
112+
}
113+
if ($this->isResidentialProxy !== false) {
114+
$js['is_residential_proxy'] = $this->isResidentialProxy;
115+
}
116+
if ($this->isTorExitNode !== false) {
117+
$js['is_tor_exit_node'] = $this->isTorExitNode;
118+
}
119+
if ($this->networkLastSeen !== null) {
120+
$js['network_last_seen'] = $this->networkLastSeen;
121+
}
122+
if ($this->providerName !== null) {
123+
$js['provider_name'] = $this->providerName;
124+
}
125+
126+
return $js;
127+
}
128+
}

‎src/Record/Traits.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@ class Traits implements \JsonSerializable
6363
* @var bool This is true if the IP address belongs to
6464
* any sort of anonymous network. This property is only available from GeoIP2
6565
* Insights.
66+
*
67+
* @deprecated use $anonymizer->isAnonymous in the Insights response instead
6668
*/
6769
public readonly bool $isAnonymous;
6870

@@ -72,6 +74,8 @@ class Traits implements \JsonSerializable
7274
* subnets under names associated with them, we will likely only flag their IP
7375
* ranges using the isHostingProvider property. This property is only available
7476
* from GeoIP2 Insights.
77+
*
78+
* @deprecated use $anonymizer->isAnonymousVpn in the Insights response instead
7579
*/
7680
public readonly bool $isAnonymousVpn;
7781

@@ -86,6 +90,8 @@ class Traits implements \JsonSerializable
8690
* @var bool This is true if the IP address belongs
8791
* to a hosting or VPN provider (see description of isAnonymousVpn property).
8892
* This property is only available from GeoIP2 Insights.
93+
*
94+
* @deprecated use $anonymizer->isHostingProvider in the Insights response instead
8995
*/
9096
public readonly bool $isHostingProvider;
9197

@@ -100,19 +106,25 @@ class Traits implements \JsonSerializable
100106
/**
101107
* @var bool This is true if the IP address belongs to
102108
* a public proxy. This property is only available from GeoIP2 Insights.
109+
*
110+
* @deprecated use $anonymizer->isPublicProxy in the Insights response instead
103111
*/
104112
public readonly bool $isPublicProxy;
105113

106114
/**
107115
* @var bool This is true if the IP address is
108116
* on a suspected anonymizing network and belongs to a residential ISP. This
109117
* property is only available from GeoIP2 Insights.
118+
*
119+
* @deprecated use $anonymizer->isResidentialProxy in the Insights response instead
110120
*/
111121
public readonly bool $isResidentialProxy;
112122

113123
/**
114124
* @var bool This is true if the IP address is a Tor
115125
* exit node. This property is only available from GeoIP2 Insights.
126+
*
127+
* @deprecated use $anonymizer->isTorExitNode in the Insights response instead
116128
*/
117129
public readonly bool $isTorExitNode;
118130

@@ -153,6 +165,17 @@ class Traits implements \JsonSerializable
153165
*/
154166
public readonly ?string $organization;
155167

168+
/**
169+
* @var float|null A risk score from 0.01 to 99 indicating the risk associated with the
170+
* IP address. A higher score indicates a higher risk. Please note that the IP
171+
* risk score provided in GeoIP products and services is more static than the
172+
* IP risk score provided in minFraud and is not responsive to traffic on your
173+
* network. If you need realtime IP risk scoring based on behavioral signals on
174+
* your own network, please use minFraud. This attribute is only available from
175+
* the GeoIP2 Insights web service.
176+
*/
177+
public readonly ?float $ipRiskSnapshot;
178+
156179
/**
157180
* @var float|null An indicator of how static or
158181
* dynamic an IP address is. This property is only available from GeoIP2
@@ -220,6 +243,7 @@ public function __construct(array $record)
220243
$this->mobileCountryCode = $record['mobile_country_code'] ?? null;
221244
$this->mobileNetworkCode = $record['mobile_network_code'] ?? null;
222245
$this->organization = $record['organization'] ?? null;
246+
$this->ipRiskSnapshot = $record['ip_risk_snapshot'] ?? null;
223247
$this->staticIpScore = $record['static_ip_score'] ?? null;
224248
$this->userCount = $record['user_count'] ?? null;
225249
$this->userType = $record['user_type'] ?? null;
@@ -291,6 +315,9 @@ public function jsonSerialize(): array
291315
if ($this->organization !== null) {
292316
$js['organization'] = $this->organization;
293317
}
318+
if ($this->ipRiskSnapshot !== null) {
319+
$js['ip_risk_snapshot'] = $this->ipRiskSnapshot;
320+
}
294321
if ($this->staticIpScore !== null) {
295322
$js['static_ip_score'] = $this->staticIpScore;
296323
}

0 commit comments

Comments
 (0)