1IP::Geolocation::MMDB(3U)ser Contributed Perl DocumentatiIoPn::Geolocation::MMDB(3)
2
3
4

NAME

6       IP::Geolocation::MMDB - Read MaxMind DB files
7

VERSION

9       version 1.010
10

SYNOPSIS

12         use IP::Geolocation::MMDB;
13         my $db = IP::Geolocation::MMDB->new(file => 'Country.mmdb');
14         my $metadata = $db->metadata;
15         my $data = $db->record_for_address('1.2.3.4');
16         my $country_code = $db->getcc('2620:fe::9');
17

DESCRIPTION

19       A Perl module that reads MaxMind DB files and maps IP addresses to
20       location information such as country and city names.
21

SUBROUTINES/METHODS

23   new
24         my $db = IP::Geolocation::MMDB->new(file => 'Country.mmdb');
25
26       Returns a new database object.  Dies if the specified file cannot be
27       read.
28
29   getcc
30         my $country_code = $db->getcc($ip_address);
31
32       Takes an IPv4 or IPv6 address as a string and returns a two-letter
33       country code or the undefined value.  Dies if the address is not a
34       valid IP address.
35
36   record_for_address
37         my $data = $db->record_for_address($ip_address);
38
39       Takes an IPv4 or IPv6 address as a string and returns the data
40       associated with the IP address or the undefined value.  Dies if the
41       address is not a valid IP address.
42
43       The returned data is usually a hash reference but could also be a an
44       array reference or a scalar for custom databases.  Here's an example
45       from an IP to city database:
46
47         {
48           city => {
49             geoname_id => 2950159,
50             names      => {
51               en => "Berlin"
52             }
53           },
54           country => {
55             geoname_id => 2921044,
56             iso_code   => "DE",
57             names      => {
58               en => "Germany",
59               fr => "Allemagne"
60             }
61           },
62           location => {
63             latitude  => 52.524,
64             longitude => 13.411
65           }
66         }
67
68   iterate_search_tree
69         sub data_callback {
70           my ($numeric_ip, $prefix_length, $data) = @_;
71         }
72
73         sub node_callback {
74           my ($node_number, $left_node_number, $right_node_number) = @_;
75         }
76
77         $db->iterate_search_tree(\&data_callback, \&node_callback);
78
79       Iterates over the entire search tree.  Calls the provided callbacks for
80       each data record and node in the tree.  Both callbacks are optional.
81
82       The data callback is called with a numeric IP address as a Math::BigInt
83       object, a network prefix length and the data associated with the
84       network.
85
86       The node callback is called with the node's number in the tree and the
87       children's node numbers.
88
89   metadata
90         my $metadata = $db->metadata;
91
92       Returns an IP::Geolocation::MMDB::Metadata object for the database.
93
94   file
95         my $file = $db->file;
96
97       Returns the file path passed to the constructor.
98
99   libmaxminddb_version
100         my $version = IP::Geolocation::MMDB::libmaxminddb_version;
101
102       Returns the libmaxminddb version.
103

DIAGNOSTICS

105       The "file" parameter is mandatory
106           The constructor was called without a database filename.
107
108       Error opening database file
109           The database file could not be read.
110
111       The IP address you provided is not a valid IPv4 or IPv6 address
112           A parameter did not contain a valid IP address.
113
114       Error looking up IP address
115           A database error occurred while looking up an IP address.
116
117       Entry data error looking up
118           A database error occurred while reading the data associated with an
119           IP address.
120
121       Error getting metadata
122           An error occurred while reading the database's metadata.
123
124       Invalid record when reading node
125           Either an invalid node was looked up or the database is corrupt.
126
127       Unknown record type
128           An unknown record type was found in the database.
129
130       Invalid depth when reading node
131           An error occurred while traversing the search tree.
132

CONFIGURATION AND ENVIRONMENT

134       None.
135

DEPENDENCIES

137       Requires Alien::libmaxminddb from CPAN.  Requires Math::BigInt version
138       1.999806, which is distributed with Perl 5.26 and newer.  Requires
139       libmaxminddb 1.2.0 or newer.
140
141       Requires an IP to country, city or ASN database in the MaxMind DB file
142       format from MaxMind <https://www.maxmind.com/> or DP-IP.com
143       <https://db-ip.com/>.
144

INCOMPATIBILITIES

146       None.
147

BUGS AND LIMITATIONS

149       If your Perl interpreter does not support 64-bit integers,
150       MMDB_DATA_TYPE_UINT64 values are put into Math::BigInt objects;
151
152       MMDB_DATA_TYPE_UINT128 values are put into Math::BigInt objects;
153
154       IP::Geolocation::MMDB can replace MaxMind::DB::Reader in many cases
155       with the following differences:
156
157       •   The classes aren't Moo classes.
158
159       •   There is no replacement for MaxMind::DB::Reader::Decoder.
160

ACKNOWLEDGEMENTS

162       Thanks to all who have contributed patches and reported bugs:
163
164       •   Yujuan Jiang
165

AUTHOR

167       Andreas Vögele <voegelas@cpan.org>
168

170       Copyright (C) 2022 Andreas Vögele
171
172       This module is free software; you can redistribute it and/or modify it
173       under the same terms as Perl itself.
174
175
176
177perl v5.38.0                      2023-07-20          IP::Geolocation::MMDB(3)
Impressum