NAME
InternetData - the official Perl client for the InternetData API
SYNOPSIS
use InternetData;
my $client = InternetData->new;
my $result = $client->lookup('146.70.116.130');
say $result->company->{name};
say 'anycast' if $result->is_anycast;
DESCRIPTION
Answers what every InternetData database says about an IP address, an AS or a domain, and downloads the databases your organization is licensed for.
Which fields a lookup answers 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 InternetData::Result, which is the one thing to read before writing an if.
METHODS
new
my $client = InternetData->new(%options);
- api_key
-
Your API key. Without one a lookup is on Unlimited, the free plan:
ip,is_bogon, the Tor, relay, anycast, carrier, satellite and service flags,locationto the country,asn,company,hostnameand the abuse email, with no daily or monthly cap. Every paid plan answers every field, and a batch needs one. The database calls need a key carrying thedb.downloadscope, and keys are default-deny, so an existing key reaches them only once the scope is added to it. 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.internetdata.io, where the lookups and the database calls both answer. "oauth" signs in at the apex,https://internetdata.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 file transfer, which is not a request whose duration a caller can predict.
- 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 download endpoint answers302and that redirect is the answer, so following it would pull a multi-gigabyte file 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 an InternetData::Result, or dies with an InternetData::Error. retries and timeout are the per-call options, as they are on lookup_asn, lookup_domain, my_ip and my_entitlement.
$ip is an IPv4 or IPv6 address. Anything else is refused before it is sent, as a bad_request naming lookup_asn and lookup_domain.
lookup_asn
my $as = $client->lookup_asn(9009);
What every database says about one AS, as an InternetData::AsnResult. The AS number is sent as given, so 'AS9009' works too. Not cached and not batched.
lookup_domain
my $domain = $client->lookup_domain('example.com');
What every database says about one domain, as an InternetData::DomainResult. Not cached and not batched.
my_ip
my $me = $client->my_ip;
Looks up the address this client is calling from, returning an InternetData::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.
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 InternetData::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 InternetData::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 InternetData 'is_bogon';
is_bogon('10.0.0.1');
database
my $databases = $client->database->list;
The licensed database downloads. Each of the seven calls takes a per-call retries option, and all but the two transfers a per-call timeout. See InternetData::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 InternetData::Oauth.
NON-BLOCKING USE
Every call has a _p twin returning a Mojo::Promise: lookup_p, lookup_asn_p, lookup_domain_p, lookup_batch_p, and the same on InternetData::Database and InternetData::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('146.70.116.130')
->then(sub { say shift->company->{name} })
->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
InternetData::Result, InternetData::AsnResult, InternetData::DomainResult, InternetData::Error, InternetData::Database, InternetData::Oauth.
LICENSE
MIT. Copyright Mslm Dev.