NAME
IP::Geolocation::MMDB - Read MaxMind DB files
VERSION
version 1.004
SYNOPSIS
use IP::Geolocation::MMDB;
my $db = IP::Geolocation::MMDB->new(file => 'Country.mmdb');
my $metadata = $db->metadata;
my $data = $db->record_for_address('1.2.3.4');
my $country_code = $db->getcc('2620:fe::9');DESCRIPTION
A Perl module that reads MaxMind DB files and maps IP addresses to location information such as country and city names.
SUBROUTINES/METHODS
new
my $db = IP::Geolocation::MMDB->new(file => 'Country.mmdb');Returns a new database object. Dies if the specified file cannot be read.
getcc
my $country_code = $db->getcc($ip_address);Takes an IPv4 or IPv6 address as a string and returns a two-letter country code or the undefined value. Dies if the address is not a valid IP address.
record_for_address
my $data = $db->record_for_address($ip_address);Takes an IPv4 or IPv6 address as a string and returns the data associated with the IP address or the undefined value. Dies if the address is not a valid IP address.
The returned data is usually a hash reference but could also be a an array reference or a scalar for custom databases. Here's an example from an IP to city database:
{
city => {
geoname_id => 2950159,
names => {
en => "Berlin"
}
},
country => {
geoname_id => 2921044,
iso_code => "DE",
names => {
en => "Germany",
fr => "Allemagne"
}
},
location => {
latitude => 52.524,
longitude => 13.411
}
}iterate_search_tree
sub data_callback {
my ($numeric_ip, $prefix_length, $data) = @_;
}
sub node_callback {
my ($node_number, $left_node_number, $right_node_number) = @_;
}
$db->iterate_search_tree(\&data_callback, \&node_callback);Iterates over the entire search tree. Calls the provided callbacks for each data record and node in the tree. Both callbacks are optional.
The data callback is called with a numeric IP address as a Math::BigInt object, a network prefix length and the data associated with the network.
The node callback is called with the node's number in the tree and the children's node numbers.
metadata
my $metadata = $db->metadata;Returns an IP::Geolocation::MMDB::Metadata object for the database.
libmaxminddb_version
my $version = IP::Geolocation::MMDB::libmaxminddb_version;Returns the libmaxminddb version.
DIAGNOSTICS
- The "file" parameter is mandatory
-
The constructor was called without a database filename.
- Error opening database file
-
The database file could not be read.
- The IP address you provided is not a valid IPv4 or IPv6 address
-
A parameter did not contain a valid IP address.
- Error looking up IP address
-
A database error occurred while looking up an IP address.
- Entry data error looking up
-
A database error occurred while reading the data associated with an IP address.
- Error getting metadata
-
An error occurred while reading the database's metadata.
- Invalid record when reading node
-
Either an invalid node was looked up or the database is corrupt.
- Unknown record type
-
An unknown record type was found in the database.
- Invalid depth when reading node
-
An error occurred while traversing the search tree.
CONFIGURATION AND ENVIRONMENT
None.
DEPENDENCIES
Requires Alien::libmaxminddb from CPAN. Requires Math::BigInt version 1.999806, which is distributed with Perl 5.26 and newer. Requires libmaxminddb 1.2.0 or newer.
Requires an IP to country, city or ASN database in the MaxMind DB file format from MaxMind or DP-IP.com.
INCOMPATIBILITIES
None.
AUTHOR
Andreas Vögele <voegelas@cpan.org>
BUGS AND LIMITATIONS
If your Perl interpreter does not support 64-bit integers, MMDB_DATA_TYPE_UINT64 values are put into Math::BigInt objects;
MMDB_DATA_TYPE_UINT128 values are put into Math::BigInt objects;
LICENSE AND COPYRIGHT
Copyright 2022 Andreas Vögele
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.