/ 
VPNDetection-1.1.0
/ VPNDetection

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. Omit it for the free tier, which answers ip and is_vpn and allows 1000 requests per day per source address.

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. Defaults to 8, and is overridable per call.

retries

Attempts after a retryable failure. Defaults to 2, and is overridable per call.

timeout

Per-request timeout in seconds. Defaults to 30.

ua

Your own Mojo::UserAgent, for a proxy or custom TLS settings. The client sets max_redirects to 0 on whichever agent it is given: the database download endpoint answers 302 and 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 is the per-call option.

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 and concurrency are the per-call options.

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 $datasets = $client->database->list;

The licensed dataset downloads. See VPNDetection::Database.

NON-BLOCKING USE

Every call has a _p twin returning a Mojo::Promise: lookup_p, lookup_batch_p, and the same on VPNDetection::Database. 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.

LICENSE

MIT. Copyright Mslm Dev.