NAME
VPNDetection - the official Perl client for the VPNDetection API
SYNOPSIS
use VPNDetection;
my $client = VPNDetection->new;
my $result = $client->lookup('45.83.91.1');
say 'VPN' if $result->is_vpn;
DESCRIPTION
Classifies an IP address as VPN infrastructure, a residential, datacenter or mobile proxy, a Tor node, a hosting provider, a CDN or a privacy relay.
Which fields come back is decided by the plan behind your key. An absent field means "not in your plan" and is not the same as false; see "ABSENT IS NOT FALSE" in VPNDetection::Result, which is the one thing to read before writing an if.
METHODS
new
my $client = VPNDetection->new(%options);
- api_key
-
Your API key. Without one a lookup is on Unlimited, the free plan:
ip,is_vpn, the Tor and relay members,locationandasn, with no daily or monthly cap. Every paid plan answers every field, and a batch needs one. An empty or blank key is the same as none, and sends noAuthorizationheader. The key is trimmed, so one read from a file with its newline works; a key still holding a control character, or a character past U+00FF, croaks here. - base_url
-
Defaults to
https://api.vpndetection.io. - cache_size
-
Addresses held in this client's cache. Defaults to 10000; 0 disables caching.
- cache_ttl
-
How long an answer stays fresh, in seconds. Defaults to 3600.
- concurrency
-
Requests in flight during a batch, a whole number from 1. Defaults to 8, and is overridable per call.
- retries
-
Attempts after a retryable failure, a whole number from 0. Defaults to 2, and is overridable per call. Each retry waits the server's
Retry-Afterwhen it sent one, otherwise a backoff of 250 ms that doubles per retry, up to 16 seconds. ARetry-Afterlonger than about 24.8 days is waited out on that backoff instead. - timeout
-
Per-request timeout in seconds. Defaults to 30, and is overridable per call. It bounds each attempt, so a retried call can take longer in total, and it is lifted for a dataset transfer.
- ua
-
Your own Mojo::UserAgent, for a proxy or custom TLS settings. The client sets
max_redirectsto 0 on whichever agent it is given: the database download endpoint answers302and that redirect is the answer, so following it would pull a multi-gigabyte dataset into memory.
The cache belongs to the client instance and is never shared. Two clients holding different keys are on different plans and entitled to different fields, so a shared cache would serve one of them the other's shape.
lookup
my $result = $client->lookup($ip, %options);
Returns a VPNDetection::Result, or dies with a VPNDetection::Error. retries and timeout are the per-call options, as they are on my_ip and my_entitlement.
my_ip
my $me = $client->my_ip;
Classifies the address this client is calling from, returning a VPNDetection::Result.
The same answer lookup would give for that address, at the same cost against your allowance. The address is the one our edge observed, so a call made through a proxy or a VPN reports the exit it left through - usually the point of asking.
Deliberately not cached. The cache is keyed by address, and which address this is IS the question: a machine that moves between networks would otherwise be told where it used to be.
my_entitlement
my $ent = $client->my_entitlement;
printf "%d of %d\n", $ent->{usage}{requests}, $ent->{usage}{quota};
What this client's API key is entitled to, and how much of it has been used, as a hash reference with org_id, apikey, plan and usage keys. Show $ent->{plan}{name} and compare against $ent->{plan}{key}: a plan's name can change, and its key never does.
Named for what it answers rather than me, which sits one letter from my_ip and means something quite different: one is which address you are calling FROM, the other is what the key you are calling WITH may spend.
Unlike a lookup there is no useful unauthenticated answer, so a client built without an API key gets an unauthorized error rather than a partial one.
Usage counts against the allowance window - on a paid plan the anniversary of the subscription, not the calendar month and not the billing period, and on a free plan the UTC day - and it is the same number a lookup is gated on. hard_limit is undef when we never stop serving, which is not the same as a limit of zero.
Deliberately not cached: the whole point is what has been spent, and a cached answer is a wrong one within seconds of the next request.
lookup_batch
my $answers = $client->lookup_batch(\@ips, %options);
Returns a hash reference keyed by address. Duplicates in @ips collapse to one request, bogons never reach the network, and an address that failed carries its VPNDetection::Error as its value instead of failing the batch. retries, concurrency and timeout are the per-call options, and the timeout bounds each chunk.
There is no cap on how many addresses one call takes: everything not answered locally goes out in chunks of up to 1000, the most one request carries. The batch endpoint needs a paid plan: without a key every address in a request of two or more carries an unauthorized VPNDetection::Error, and a free-plan key's request of two or more a bad_request one (HTTP 402). A request of one address is answered as its lookup would be.
Perl hashes have no insertion order, so iterate your own list if order matters:
for my $ip (@ips) {
my $answer = $answers->{$ip};
}
is_bogon
$client->is_bogon('10.0.0.1'); # 1
Also exportable, for code with no client to hand:
use VPNDetection 'is_bogon';
is_bogon('10.0.0.1');
database
my $databases = $client->database->list;
The licensed dataset downloads. See VPNDetection::Database.
oauth
my $device = $client->oauth->device_authorization('your-client-id');
Signs a person in on their own machine with the OAuth device flow, so a program can be handed one of their API keys instead of asking for it. See VPNDetection::Oauth.
NON-BLOCKING USE
Every call has a _p twin returning a Mojo::Promise: lookup_p, lookup_batch_p, and the same on VPNDetection::Database and VPNDetection::Oauth. The blocking forms are those promises plus a wait, so nothing is duplicated and both paths retry, cache and short-circuit identically.
$client->lookup_p('45.83.91.1')
->then(sub { say shift->is_vpn })
->catch(sub { warn shift })
->wait;
Inside an already running Mojo::IOLoop - a Mojolicious application, say - the blocking forms cannot work and croak saying so. Use the _p forms there.
SEE ALSO
VPNDetection::Result, VPNDetection::Error, VPNDetection::Database, VPNDetection::Oauth.
LICENSE
MIT. Copyright Mslm Dev.