NAME
Net::IPData - Perl client for the ipdata.co IP geolocation and threat intelligence API
SYNOPSIS
use Net::IPData;
my $ipdata = Net::IPData->new(api_key => 'YOUR_API_KEY');
# Look up a specific IP address
my $result = $ipdata->lookup('8.8.8.8');
printf "IP: %s, Country: %s, City: %s\n",
$result->{ip}, $result->{country_name}, $result->{city};
# Flags the API includes only when true (a missing key reads as false)
print "satellite ISP\n" if $result->{is_satellite};
print "anycast address\n" if $result->{is_anycast};
# Look up your own IP address
my $me = $ipdata->lookup_mine();
# Request only specific fields
my $partial = $ipdata->lookup('8.8.8.8', fields => [qw(ip country_name asn)]);
# Bulk lookup (up to 100 IPs)
my $results = $ipdata->bulk(['8.8.8.8', '1.1.1.1']);
# Get a single field directly
my $asn = $ipdata->asn('8.8.8.8');
my $threat = $ipdata->threat('8.8.8.8');
my $country = $ipdata->country_name('8.8.8.8');
# Use the EU endpoint for GDPR compliance
my $eu = Net::IPData->new(api_key => 'YOUR_API_KEY', eu => 1);
DESCRIPTION
Net::IPData provides a Perl interface to the ipdata.co API, which offers IP geolocation, ASN, company, carrier, threat intelligence, currency, timezone, and language data for any IPv4 or IPv6 address.
This module uses only Perl core modules (HTTP::Tiny, JSON::PP) and has no non-core dependencies.
CONSTRUCTOR
new
my $ipdata = Net::IPData->new(
api_key => 'YOUR_API_KEY', # required
eu => 0, # use EU endpoint (default: 0)
base_url => '...', # custom base URL (overrides eu)
timeout => 30, # HTTP timeout in seconds (default: 30)
keep_alive => 1, # reuse the HTTPS connection (default: 1)
keep_alive_timeout => 60, # idle timeout in seconds (default: none)
verify_ssl => 1, # verify the server certificate (default: 1)
ua => $user_agent, # your own HTTP::Tiny-compatible object
);
- keep_alive
-
Whether the underlying HTTP::Tiny keeps its connection to the API open between requests (default 1). Set it to 0 to open a fresh connection for every request. Not applied when
uais supplied. - keep_alive_timeout
-
Idle timeout in seconds for the kept-alive connection: once it has gone unused for longer than this, the next request opens a fresh connection instead of reusing it. Honoured by HTTP::Tiny 0.092 and later, whose own default (no limit) applies when you leave it unset; older HTTP::Tiny has no such setting and ignores it, in which case the value is merely stored (see "ACCESSORS"). api.ipdata.co keeps idle connections open for roughly two minutes, so 60 is a sensible value. Not applied when
uais supplied. - verify_ssl
-
Whether the API server's TLS certificate is verified (chain and host name), default 1. The value is passed to HTTP::Tiny as
verify_SSL, so certificates are checked with every HTTP::Tiny version, not only with 0.083 and later (which verify by default), and independently of HTTP::Tiny'sPERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULTenvironment variable. Verification needs a CA bundle: HTTP::Tiny uses Mozilla::CA when it is installed and otherwise the operating system's bundle (see "SSL SUPPORT" in HTTP::Tiny); without one every request fails with aNetwork error. Set it to 0 only when you must talk to a server whose certificate cannot be verified, for example a local test endpoint given asbase_url: the connection is still encrypted but the server's identity is not checked. Not applied whenuais supplied. - ua
-
An object to use instead of a new HTTP::Tiny: anything with HTTP::Tiny-compatible
get($url)andpost($url, \%options)methods that return a hashref withstatus,content,headersandsuccess. Use it to share one pre-configured HTTP::Tiny (proxy,SSL_optionssuch as a private CA file) or to inject a mock in tests.timeout,keep_alive,keep_alive_timeoutandverify_sslare not applied to a supplied object; configure it yourself.
CONNECTION REUSE
A Net::IPData object keeps one persistent HTTPS connection (HTTP/1.1 keep-alive) for as long as it lives. Create one client per process (or one per API key or endpoint), keep it, and reuse it for every lookup: each new client pays a fresh TLS handshake. HTTP/2 is not available with HTTP::Tiny, so the saving is the TLS handshake, not multiplexing.
The reuse is HTTP::Tiny's own (keep_alive => 1): the connection is reused while the server keeps it open, a connection the server has already closed is detected and replaced transparently, and a GET on a socket that died silently is retried once by HTTP::Tiny itself. The non-idempotent POST /bulk request gets the same single retry from this module, but only when the failure happened at the socket level before any response arrived (HTTP::Tiny status 599 with a Socket closed, Unexpected end of stream or Connection reset error). A request that received an HTTP status is never retried. With HTTP::Tiny 0.092 or later, keep_alive_timeout => 60 additionally stops reusing a connection that has been idle for a minute, before the server (which keeps idle connections for roughly two minutes) can drop it silently.
A Net::IPData object is not shared between threads: use one object per thread. It is fork-safe: HTTP::Tiny 0.049 and later records the process and thread that opened the connection and never reuses a socket inherited from another process or thread, so a forked child opens its own connection on its first request.
There is nothing to close explicitly. The connection is shut down when the object is destroyed, so letting it go out of scope (or undef $ipdata) at shutdown is all the cleanup needed. Pass keep_alive => 0 to open a new connection per request, or your own ua to control the transport completely.
REQUEST HEADERS
Every request carries Accept: application/json and the user agent ipdata-perl/VERSION, VERSION being the module version. The bulk POST, the only request with a body, also sends Content-Type: application/json; GET requests send no Content-Type. A supplied ua uses its own default headers and user agent, but still receives the bulk Content-Type, which the module passes with each POST.
METHODS
lookup($ip, %opts)
Look up an IP address. If $ip is omitted or undef, looks up the caller's IP address.
Options:
- fields => \@fields | $comma_separated_string
-
Request only the specified fields. Reduces response size.
Returns a hashref of the API response.
lookup_mine(%opts)
Look up the IP address of the machine making the request. Accepts the same options as lookup.
lookup_field($ip, $field)
Retrieve a single field for an IP address via the path-based API (e.g., /8.8.8.8/country_name). Returns the field value directly, which may be a string, number, boolean, hashref, or arrayref depending on the field.
bulk(\@ips, %opts)
Look up multiple IP addresses in a single request (maximum 100). Sends a POST request to the /bulk endpoint. Accepts the same fields option as lookup. If the kept-alive connection turns out to be dead before any response arrived, the request is retried once (see "CONNECTION REUSE").
Returns an arrayref of result hashrefs.
Convenience Methods
The following methods call lookup_field for common fields:
- asn($ip) - ASN information (hashref)
- threat($ip) - Threat intelligence (hashref)
- carrier($ip) - Mobile carrier info (hashref)
- currency($ip) - Currency data (hashref)
- time_zone($ip) - Timezone data (hashref)
- languages($ip) - Language list (arrayref)
- country_name($ip) - Country name (string)
- country_code($ip) - Country code (string)
- is_eu($ip) - EU membership (boolean)
- is_satellite($ip) - Satellite internet provider flag (boolean)
- is_anycast($ip) - Anycast address flag (boolean)
ACCESSORS
- api_key - The API key
- base_url - The base URL being used
- timeout - The HTTP timeout value
- keep_alive - Whether the HTTPS connection is kept alive between requests (default 1)
- keep_alive_timeout - The idle timeout given to the constructor, or undef
- verify_ssl - Whether the server certificate is verified (default 1)
- ua - The user agent object (an HTTP::Tiny unless one was injected)
ERROR HANDLING
All methods will croak on errors. Catch them with eval or Try::Tiny:
use Try::Tiny;
try {
my $result = $ipdata->lookup('invalid');
} catch {
warn "API error: $_";
};
Error messages include the HTTP status code and the API's error message when available.
API RESPONSE STRUCTURE
A full lookup returns a hashref with the following keys:
ip, is_eu, is_satellite, is_anycast,
city, region, region_code, region_type,
country_name, country_code, continent_name, continent_code,
latitude, longitude, postal, calling_code, flag,
emoji_flag, emoji_unicode,
asn => { asn, name, domain, route, type },
company => { name, domain, network, type },
carrier => { name, mcc, mnc },
languages => [{ name, native, code }],
currency => { name, code, symbol, native, plural },
time_zone => { name, abbr, offset, is_dst, current_time },
threat => { is_tor, is_vpn, is_icloud_relay, is_proxy, is_datacenter,
is_anonymous, is_known_attacker, is_known_abuser,
is_threat, is_bogon,
blocklists => [{ name, site, type,
first_seen, last_seen, days_seen }],
scores => { vpn_score, proxy_score,
threat_score, trust_score } },
count => N (for bulk lookups)
The JSON is passed through unchanged, so keys the API adds later simply appear in the hashref. Five fields deserve a note:
- is_satellite
-
True when the address belongs to a satellite internet provider. The API includes this key only when it is true and omits it otherwise, so test it with a plain boolean check (
if ($result->{is_satellite})), never withexists; a missing key reads as false. - is_anycast
-
True when the address is an anycast address. Present only when true, like
is_satellite. - first_seen, last_seen (per
threat->{blocklists}entry) -
The first and the most recent calendar date (UTC,
YYYY-MM-DD) on which that blocklist listed the address. The module leaves them as strings. - days_seen (per
threat->{blocklists}entry) -
The number of days that blocklist has listed the address (integer).
Some feeds, for example ipdata's own vpn feed, omit all three blocklist fields, so check for them with exists before use. Bulk results carry the same shape per item.
REQUIREMENTS
Perl 5.10.1 or later. Only core modules are required:
HTTP::Tiny 0.049 or later (core since Perl 5.14; 0.049 ships with Perl 5.22 and later, older Perls install it from CPAN)
JSON::PP (core since Perl 5.14)
Carp (core)
Scalar::Util (core)
HTTPS itself needs IO::Socket::SSL 1.56 and Net::SSLeay 1.49 or later, plus a CA bundle (Mozilla::CA or the operating system's) for the certificate verification that is on by default (see "verify_ssl"). They are recommended rather than required prerequisites so that the module can be installed where they are not available.
SEE ALSO
https://docs.ipdata.co/ - ipdata API documentation
https://ipdata.co/ - ipdata website
LICENSE
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHOR
Net::IPData contributors