1GeoIP2::Database::ReadeUrs(e3r)Contributed Perl DocumentGaetoiIoPn2::Database::Reader(3)
2
6 GeoIP2::Database::Reader - Perl API for GeoIP2 databases
7
9 version 2.006002
10
12 use 5.008;
13 use GeoIP2::Database::Reader;
15 my $reader = GeoIP2::Database::Reader->new(
17 file => '/path/to/database', # e.g. /home/maxmind/db/GeoIP2-Country.mmdb
18 locales => [ 'en', 'de', ]
19 );
20 my $city = $reader->city( ip => '24.24.24.24' );
22 my $country = $city->country();
23 print $country->iso_code(), "\n";
24
26 This class provides a reader API for all GeoIP2 databases. Each method
27 returns a different model class.
28 If the database does not return a particular piece of data for an IP
30 address, the associated attribute is not populated.
31
33 The basic API for this class is the same for all database types. First
34 you create a database reader object with your "file" and "locale"
35 params. Then you call the method corresponding to your database type,
36 passing it the IP address you want to look up.
37 If the request succeeds, the method call will return a model class for
39 the method point you called.
40 If the database cannot be read, the reader class throws an exception.
42
44 IP geolocation is inherently imprecise. Locations are often near the
45 center of the population. Any location provided by a GeoIP2 database
46 should not be used to identify a particular address or household.
47
49 This class has a single constructor method:
50 GeoIP2::Database::Reader->new()
52 This method creates a new object. It accepts the following arguments:
53 • file
55 This is the path to the GeoIP2 database which you'd like to query.
57 The path should include the filename.
58 • locales
60 This is an array reference where each value is a string indicating
62 a locale. This argument will be passed on to record classes to use
63 when their "name()" methods are called.
64 The order of the locales is significant. When a record class has
66 multiple names (country, city, etc.), its "name()" method will look
67 at each element of this array ref and return the first locale for
68 which it has a name.
69 Note that the only locale which is always present in the GeoIP2
71 data in "en". If you do not include this locale, the "name()"
72 method may end up returning "undef" even when the record in
73 question has an English name.
74 Currently, the valid list of locale codes is:
76 • de - German
78 • en - English
80 English names may still include accented characters if that
82 is the accepted spelling in English. In other words,
83 English does not mean ASCII.
84 • es - Spanish
86 • fr - French
88 • ja - Japanese
90 • pt-BR - Brazilian Portuguese
92 • ru - Russian
94 • zh-CN - simplified Chinese
96 Passing any other locale code will result in an error.
98 The default value for this argument is "['en']".
100
102 All of the request methods accept a single argument:
103 • ip
105 This must be a valid IPv4 or IPv6 address. This is the address that
107 you want to look up using the GeoIP2 web service.
108 Unlike the web service client class, you cannot pass the string
110 "me" as your ip address.
111 $reader->asn()
113 This method returns a GeoIP2::Model::ASN object.
114 $reader->connection_type()
116 This method returns a GeoIP2::Model::ConnectionType object.
117 $reader->country()
119 This method returns a GeoIP2::Model::Country object.
120 $reader->city()
122 This method returns a GeoIP2::Model::City object.
123 $reader->domain()
125 This method returns a GeoIP2::Model::Domain object.
126 $reader->isp()
128 This method returns a GeoIP2::Model::ISP object.
129 $reader->enterprise()
131 This method returns a GeoIP2::Model::Enterprise object.
132 $reader->anonymous_ip()
134 This method returns a GeoIP2::Model::AnonymousIP object.
135
137 $reader->metadata()
138 This method returns a MaxMind::DB::Metadata object containing
139 information about the database.
140
142 In the case of a fatal error, the reader will throw a
143 GeoIP2::Error::Generic or GeoIP2::Error::IPAddressNotFound exception
144 object.
145 This error class has an "$error->message()" method and overload
147 stringification to show that message. This means that if you don't
148 explicitly catch errors they will ultimately be sent to "STDERR" with
149 some sort of (hopefully) useful error message.
150
152 While many of the databases return the same basic records, the
153 attributes which can be populated vary between model classes. In
154 addition, while a database may offer a particular piece of data,
155 MaxMind does not always have every piece of data for any given IP
156 address.
157 Because of these factors, it is possible for any model class to return
159 a record where some or all of the attributes are unpopulated.
160 See <http://dev.maxmind.com/geoip/geoip2/web-services> for details on
162 what data each end point may return.
163 Every record class attribute has a corresponding predicate method so
165 you can check to see if the attribute is set.
166
168 Bugs may be submitted through
169 <https://github.com/maxmind/GeoIP2-perl/issues>.
170
172 • Dave Rolsky <drolsky@maxmind.com>
173 • Greg Oschwald <goschwald@maxmind.com>
175 • Mark Fowler <mfowler@maxmind.com>
177 • Olaf Alders <oalders@maxmind.com>
179
181 This software is copyright (c) 2013 - 2019 by MaxMind, Inc.
182 This is free software; you can redistribute it and/or modify it under
184 the same terms as the Perl 5 programming language system itself.
185perl v5.34.0 2021-07-22 GeoIP2::Database::Reader(3)