IP::Ge...n::MMDB(3pm)

📦
version 1.013 · 4 versions
, in debian trixie, ubuntu resolute

💖 IP::Geolocation::MMDB 💖

okay bestie, so this is a page from the User Contributed Perl Documentation — it's the manual for IP::Geolocation::MMDB, and I'm about to make it make sense. no cap. 🫶

✨ NAME ✨

IP::Geolocation::MMDB — Read MaxMind DB files 🔥

🌸 VERSION 🌸

version 1.013

🎀 SYNOPSIS 🎀

use IP::Geolocation::MMDB;
my $db = IP::Geolocation::MMDB->new(file => '/path/to/Country.mmdb');
my $metadata = $db->metadata;
my $data = $db->get('1.2.3.4');
my $country_code = $db->getcc('2620:fe::9');

like... that's it. that's the whole vibe. 💅

🦋 DESCRIPTION 🦋

A Perl module that reads MaxMind DB files and maps IP addresses to location information such as country and city names. literally it takes an IP and tells you where that IP is from. main character energy fr fr. ✨

👑 SUBROUTINES/METHODS 👑

💜 new

my $db = IP::Geolocation::MMDB->new(file => '/path/to/Country.mmdb');

Returns a new database object. Dies if the specified file cannot be read. so like, if that file isn't there, it's over, no notes. 😭

💜 get

my $data = $db->get($ip_address);
my ($data, $prefix_length) = $db->get($ip_address);

Takes an IPv4 or IPv6 address as a string and returns the data associated with the IP address or the undefined value. In list context, the data and the network prefix length associated with the IP address are returned. Dies if the address is not a valid IP address. so give it a real IP, bestie, not vibes. 🙈

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

it's giving Berlin. iconic. 🍓

💜 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. just the country code, nothing extra, we love a minimal queen. 🌈

💜 record_for_address

my $data = $db->record_for_address($ip_address);

An alias for "get" that always returns a scalar. so like, same energy, but it never gives you the list-context situation. simple. 🫶

💜 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. so you can pass one, both, or honestly neither — no pressure bestie. ✨

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. the lore about your database. 📖

💜 file

my $file = $db->file;

Returns the file path passed to the constructor. yes, it remembers. 🥰

💜 libmaxminddb_version

my $version = IP::Geolocation::MMDB::libmaxminddb_version;

Returns the libmaxminddb version.

💀 DIAGNOSTICS 💀

like, here's every way this can go wrong, so you're not blindsided:

  • The "file" parameter is mandatory — The constructor was called without a database filename. you forgot the file, bestie. 💀
  • 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. nothing to configure. it just works. slay. 💅

📦 DEPENDENCIES 📦

Requires Math::BigInt version 1.999806, which is distributed with Perl 5.26 and newer. Requires libmaxminddb 1.2.0 or newer.

Requires a database in the MaxMind DB file format from MaxMind <https://www.maxmind.com/> or DP-IP.com <https://db-ip.com/>.

Alien::libmaxminddb from CPAN is a build dependency. The built module does only depend on modules that are distributed with Perl.

Install "pkg-config" and "libmaxminddb-devel" or "libmaxminddb-dev" if you would like to use your operating system's libmaxminddb library.

🚫 INCOMPATIBILITIES 🚫

None. we play nice with everyone. 🫶

😭 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.

IP::Geolocation::MMDB can replace MaxMind::DB::Reader in many cases with the following differences:

  • The classes aren't Moo classes.
  • There is no replacement for MaxMind::DB::Reader::Decoder.

Create the file MaxMind/DB/Reader.pm in your @INC path if you want to try IP::Geolocation::MMDB as a replacement for MaxMind::DB::Reader:

use IP::Geolocation::MMDB;
@MaxMind::DB::Reader::ISA = qw(IP::Geolocation::MMDB);
1;

like, drop-in replacement era. 🔥

👀 SEE ALSO 👀

See Geo::Location::IP for object-oriented wrapper classes. iykyk. 🌸

💖 ACKNOWLEDGEMENTS 💖

Thanks to all who have contributed patches and reported bugs:

  • Yujuan Jiang

we see you, we appreciate you, thank you for your service. 🫶✨

✍️ AUTHOR ✍️

Andreas Vögele <voegelas@cpan.org>

Copyright (C) 2025 Andreas Vögele

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page bestie, mwah 💅

this was perl v5.40.1, dated 2025-03-20 — IP::Ge...n::MMDB(3pm), User Contributed Perl Documentation. go read some IPs, you got this. 🦋✨

📦 where this page comes from