/ 
Net-IPData-1.0.0
/ Net::IPData

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};

# 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)
);

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.

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)

ACCESSORS

api_key - The API key
base_url - The base URL being used
timeout - The HTTP timeout value

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, 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_icloud_relay, is_proxy, is_datacenter,
              is_anonymous, is_known_attacker, is_known_abuser,
              is_threat, is_bogon },
count    => N  (for bulk lookups)

REQUIREMENTS

Perl 5.10.1 or later. Only core modules are required:

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