WebService::AbuseIPDB - Client for the API (version 2) of AbuseIPDB


    use WebService::AbuseIPDB;

    my $ipdb = WebService::AbuseIPDB->new (key => 'abc123...');
    my $res = $ipdb->check (ip => '');
    die unless defined $res;
    printf "There is a %i%% chance this address is up to no good.\n",

DESCRIPTION|AbuseIPDB maintains a database of reports of bad actors on the net. Users may interface with the database through a web browser using forms on their site. An alternative is to use their API. Version 1 of this API is to be retired in 2020. This module serves as a client for Version 2 of the API.



    my $ipdb = WebService::AbuseIPDB->new (%opts);

The constructor takes a hash of configuration details.


The API version - always set this as "2" to avoid potential problems with mismatched versions.


Your key for the API as a scalar string. You must obtain one before using this module.


The timeout in seconds to wait for the server to respond. Defaults to 20.


The number of times to retry on timeout or network error. Defaults to 0 (ie. no retries).


    my $res = $ipdb->check (ip => '', max_age => 90);

This uses the check endpoint and returns a WebService::AbuseIPDB::CheckResponse object to access the data held in the database for the provided IP address. The argument is a hash with these keys:


The IP address to be checked. This item is mandatory.


The age in integral days of the oldest report(s) to include. If omitted the server default is used (currently 30).


If set to any true value, the data from each report itself is also returned. Not yet impelemented.


    my $res = $ipdb->report (
        ip          => '',
        categories  => [3, 4],
        comment     => 'This address is the worst'

This uses the report endpoint to report an abusive address. It takes a single hash as the only argument with these elements:


The IP address to report. Must be a single, valid IPv4 or IPv6 address. This element is mandatory.


An arrayref of categories as either scalar IDs or scalar names or WebService::AbuseIPDB::Category objects. This element is mandatory.


A scalar string with details of the offence. This is optional but recommended in most cases. It must be no more than 1024 characters. and should be decoded.

The method will return undef on client error and a WebService::AbuseIPDB::ReportResponse object otherwise.


    my $res = $ipdb->blacklist (
        min_abuse   => 90,
        limit       => 1000
    print "As at " . $res->as_at . "\n";
    for my $bad ($res->list) {
        printf "Address %s has score %i%%\n", $bad->ip, $bad->score;

This uses the blacklist endpoint to retrieve a list of abusive addresses. It takes a single hash as the only argument with these elements:


Only include addresses with an abuse confidence score of this level or higher. Minimum is 25, maximum is 100 and default is 75.


An integer giving the maximum quantity of addresses to return. Minimum is 1, maximum is 10,000 for non-subscribers and default is 1000.

The method will return undef on client error and a WebService::AbuseIPDB::BlacklistResponse object otherwise.


This is currently alpha software. Be aware that both the internals and the interface are liable to change.


Implement the verbose option on the check method.

Add the other API endpoints: check-block and bulk-report. Allow for fast blacklist-as-string response too.

More validation/sanitation of inputs.

Consider using objects for errors instead of AoH.


SendMail::AbuseIPDB is a client for v1 of the API.

Full documentation for the API is at


Pete Houston, <cpan at>


Please report any bugs or feature requests to bug-webservice-abuseipdb at, or through the web interface at See the file for further details.


Thanks to AbuseIPDB for making the database publicly available via this API.


Copyright © 2020 Pete Houston.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991 or at your option any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is available in the source tree; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA