Geo::IP(3pm)

1Geo::IP(3)            User Contributed Perl Documentation           Geo::IP(3)
2
3
4

NAME

6       Geo::IP - Look up location and network information by IP Address
7

VERSION

9       version 1.51
10

SYNOPSIS

12         use Geo::IP;
13         my $gi = Geo::IP->new(GEOIP_MEMORY_CACHE);
14         # look up IP address '24.24.24.24'
15         # returns undef if country is unallocated, or not defined in our database
16         my $country = $gi->country_code_by_addr('24.24.24.24');
17         $country = $gi->country_code_by_name('yahoo.com');
18         # $country is equal to "US"
19
20
21         use Geo::IP;
22         my $gi = Geo::IP->open("/usr/local/share/GeoIP/GeoIPCity.dat", GEOIP_STANDARD);
23         my $record = $gi->record_by_addr('24.24.24.24');
24         print $record->country_code,
25               $record->country_code3,
26               $record->country_name,
27               $record->region,
28               $record->region_name,
29               $record->city,
30               $record->postal_code,
31               $record->latitude,
32               $record->longitude,
33               $record->time_zone,
34               $record->area_code,
35               $record->continent_code,
36               $record->metro_code;
37
38
39         # the IPv6 support is currently only avail if you use the CAPI which is much
40         # faster anyway. ie: print Geo::IP->api equals to 'CAPI'
41         use Socket;
42         use Socket6;
43         use Geo::IP;
44         my $g = Geo::IP->open('/usr/local/share/GeoIP/GeoIPv6.dat') or die;
45         print $g->country_code_by_ipnum_v6(inet_pton AF_INET6, '::24.24.24.24');
46         print $g->country_code_by_addr_v6('2a02:e88::');
47

DESCRIPTION

49       This module uses the GeoIP Legacy file based database.  This database
50       simply contains IP blocks as keys, and countries as values. This
51       database should be more complete and accurate than reverse DNS lookups.
52
53       This module can be used to automatically select the geographically
54       closest mirror, to analyze your web server logs to determine the
55       countries of your visitors, for credit card fraud detection, and for
56       software export controls.
57

IP GEOLOCATION USAGE

59       IP geolocation is inherently imprecise. Locations are often near the
60       center of the population. Any location provided by a GeoIP database or
61       web service should not be used to identify a particular address or
62       household.
63

IP ADDRESS TO COUNTRY DATABASES

65       Free monthly updates to the database are available from
66
67         http://dev.maxmind.com/geoip/geolite
68
69       This free database is similar to the database contained in IP::Country,
70       as well as many paid databases. It uses ARIN, RIPE, APNIC, and LACNIC
71       whois to obtain the IP->Country mappings.
72
73       If you require greater accuracy, MaxMind offers a database on a paid
74       subscription basis.  Also included with this is a service that updates
75       your database automatically each month, by running a program called
76       geoipupdate included with the C API from a cronjob.  For more details
77       on the differences between the free and paid databases, see:
78
79       http://www.maxmind.com/en/geolocation_landing
80
81       Do not miss the city database, described in Geo::IP::Record
82
83       Make sure to use the geolite-mirror-simple.pl script from the example
84       directory to stay current with the databases.
85

BENCHMARK the lookups are fast. This is my laptop ( examples/benchmark.pl ):

87         Benchmark: running city_mem, city_std, country_mem, country_std, country_v6_mem, country_v6_std, isp_mem, isp_std for at least 10 CPU seconds...
88           city_mem: 10.3121 wallclock secs (10.30 usr +  0.01 sys = 10.31 CPU) @ 387271.48/s (n=3992769)
89           city_std: 10.0658 wallclock secs ( 2.86 usr +  7.17 sys = 10.03 CPU) @ 54392.62/s (n=545558)
90         country_mem: 10.1772 wallclock secs (10.16 usr +  0.00 sys = 10.16 CPU) @ 1077507.97/s (n=10947481)
91         country_std: 10.1432 wallclock secs ( 2.30 usr +  7.85 sys = 10.15 CPU) @ 83629.56/s (n=848840)
92         country_v6_mem: 10.2579 wallclock secs (10.25 usr + -0.00 sys = 10.25 CPU) @ 365997.37/s (n=3751473)
93         country_v6_std: 10.8541 wallclock secs ( 1.77 usr +  9.07 sys = 10.84 CPU) @ 10110.42/s (n=109597)
94            isp_mem: 10.147 wallclock secs (10.13 usr +  0.01 sys = 10.14 CPU) @ 590109.66/s (n=5983712)
95            isp_std: 10.0484 wallclock secs ( 2.71 usr +  7.33 sys = 10.04 CPU) @ 73186.35/s (n=734791)
96

CLASS METHODS

98       $gi = Geo::IP->new( $flags );
99           Constructs a new Geo::IP object with the default database located
100           inside your system's datadir, typically
101           /usr/local/share/GeoIP/GeoIP.dat.
102
103           Flags can be set to either GEOIP_STANDARD, or for faster
104           performance (at a cost of using more memory), GEOIP_MEMORY_CACHE.
105           When using memory cache you can force a reload if the file is
106           updated by setting GEOIP_CHECK_CACHE.  GEOIP_INDEX_CACHE caches the
107           most frequently accessed index portion of the database, resulting
108           in faster lookups than GEOIP_STANDARD, but less memory usage than
109           GEOIP_MEMORY_CACHE - useful for larger databases such as GeoIP
110           Legacy Organization and GeoIP City. Note, for GeoIP Country, Region
111           and Netspeed databases, GEOIP_INDEX_CACHE is equivalent to
112           GEOIP_MEMORY_CACHE.
113
114           Prior to geoip-api version 1.6.3, the C API would leak diagnostic
115           messages onto stderr unconditionally. From Geo::IP v1.44 onwards,
116           the flag squelching this behavior (GEOIP_SILENCE) is implicitly
117           added to the flags passed in new(), open(), and open_type().
118
119           To combine flags, use the bitwise OR operator, |.  For example, to
120           cache the database in memory, but check for an updated GeoIP.dat
121           file, use: Geo::IP->new( GEOIP_MEMORY_CACHE | GEOIP_CHECK_CACHE );
122
123       $gi = Geo::IP->open( $database_filename, $flags );
124           Constructs a new Geo::IP object with the database located at
125           $database_filename.
126
127       $gi = Geo::IP->open_type( $database_type, $flags );
128           Constructs a new Geo::IP object with the $database_type database
129           located in the standard location.  For example
130
131             $gi = Geo::IP->open_type( GEOIP_CITY_EDITION_REV1 , GEOIP_STANDARD );
132
133           opens the database file in the standard location for GeoIP Legacy
134           City, typically /usr/local/share/GeoIP/GeoIPCity.dat.
135

OBJECT METHODS

137       $code = $gi->country_code_by_addr( $ipaddr );
138           Returns the ISO 3166 country code for an IP address.
139
140       $code = $gi->country_code_by_name( $hostname );
141           Returns the ISO 3166 country code for a hostname.
142
143       $code = $gi->country_code3_by_addr( $ipaddr );
144           Returns the 3 letter country code for an IP address.
145
146       $code = $gi->country_code3_by_name( $hostname );
147           Returns the 3 letter country code for a hostname.
148
149       $name = $gi->country_name_by_addr( $ipaddr );
150           Returns the full country name for an IP address.
151
152       $name = $gi->country_name_by_name( $hostname );
153           Returns the full country name for a hostname.
154
155       $r = $gi->record_by_addr( $ipaddr );
156           Returns a Geo::IP::Record object containing city location for an IP
157           address.
158
159       $r = $gi->record_by_name( $hostname );
160           Returns a Geo::IP::Record object containing city location for a
161           hostname.
162
163       $org = $gi->org_by_addr( $ipaddr ); deprecated use "name_by_addr"
164       instead.
165           Returns the Organization, ISP name or Domain Name for an IP
166           address.
167
168       $org = $gi->org_by_name( $hostname );  deprecated use "name_by_name"
169       instead.
170           Returns the Organization, ISP name or Domain Name for a hostname.
171
172       $info = $gi->database_info;
173           Returns database string, includes version, date, build number and
174           copyright notice.
175
176       $old_charset = $gi->set_charset( $charset );
177           Set the charset for the city name - defaults to
178           GEOIP_CHARSET_ISO_8859_1.  To set UTF8, pass GEOIP_CHARSET_UTF8 to
179           set_charset.  For perl >= 5.008 the utf8 flag is honored.
180
181       $charset = $gi->charset;
182           Gets the currently used charset.
183
184       ( $country, $region ) = $gi->region_by_addr('24.24.24.24');
185           Returns a list containing country and region. If region and/or
186           country is unknown, undef is returned. Sure this works only for
187           region databases.
188
189       ( $country, $region ) = $gi->region_by_name('www.xyz.com');
190           Returns a list containing country and region. If region and/or
191           country is unknown, undef is returned. Sure this works only for
192           region databases.
193
194       $netmask = $gi->last_netmask;
195           Gets netmask of network block from last lookup.
196
197       $gi->netmask(12);
198           Sets netmask for the last lookup
199
200       my ( $from, $to ) = $gi->range_by_ip('24.24.24.24');
201           Returns the start and end of the current network block. The method
202           tries to join several continuous netblocks.
203
204       $api = $gi->api or $api = Geo::IP->api
205           Returns the currently used API.
206
207             # prints either CAPI or PurePerl
208             print Geo::IP->api;
209
210       $continent = $gi->continent_code_by_country_code('US');
211           Returns the continent code by country code.
212
213       $dbe = $gi->database_edition
214           Returns the database_edition of the currently opened database.
215
216             if ( $gi->database_edition == GEOIP_COUNTRY_EDITION ){
217               ...
218             }
219
220       $isp = $gi->isp_by_addr('24.24.24.24');
221           Returns the isp for 24.24.24.24
222
223       $isp = $gi->isp_by_name('www.maxmind.com');
224           Returns the isp for www.something.de
225
226       my $time_zone = $gi->time_zone('US', 'AZ');
227           Returns the time zone for country/region.
228
229             # undef
230             print  $gi->time_zone('US', '');
231
232             # America/Phoenix
233             print  $gi->time_zone('US', 'AZ');
234
235             # Europe/Berlin
236             print  $gi->time_zone('DE', '00');
237
238             # Europe/Berlin
239             print  $gi->time_zone('DE', '');
240
241       $id = $gi->id_by_addr('24.24.24.24');
242           Returns the country_id for 24.24.24.24. The country_id might be
243           useful as array index. 0 is unknown.
244
245       $id = $gi->id_by_name('www.maxmind.com');
246           Returns the country_id for www.maxmind.com. The country_id might be
247           useful as array index. 0 is unknown.
248
249       $cc = $gi->country_code3_by_addr_v6('::24.24.24.24');
250       $cc = $gi->country_code3_by_name_v6('ipv6.google.com');
251       $cc = $gi->country_code_by_addr_v6('2a02:ea0::');
252       $cc = $gi->country_code_by_ipnum_v6($ipnum);
253             use Socket;
254             use Socket6;
255             use Geo::IP;
256             my $g = Geo::IP->open('/usr/local/share/GeoIP/GeoIPv6.dat') or die;
257             print $g->country_code_by_ipnum_v6(inet_pton AF_INET6, '::24.24.24.24');
258
259       $cc = $gi->country_code_by_name_v6('ipv6.google.com');
260       name_by_addr
261           Returns the Organization, ISP name or Domain Name for a IP address.
262
263       name_by_addr_v6
264           Returns the Organization, ISP name or Domain Name for an IPv6
265           address.
266
267       name_by_ipnum_v6
268           Returns the Organization, ISP name or Domain Name for an ipnum.
269
270       name_by_name
271           Returns the Organization, ISP name or Domain Name for a hostname.
272
273       name_by_name_v6
274           Returns the Organization, ISP name or Domain Name for a hostname.
275
276       org_by_addr_v6 deprecated use "name_by_addr_v6"
277           Returns the Organization, ISP name or Domain Name for an IPv6
278           address.
279
280       org_by_name_v6  deprecated use "name_by_name_v6"
281           Returns the Organization, ISP name or Domain Name for a hostname.
282
283       teredo
284           Returns the current setting for teredo.
285
286       enable_teredo
287           Enable / disable teredo
288
289             $gi->enable_teredo(1); # enable
290             $gi->enable_teredo(0); # disable
291
292       lib_version
293             if ( $gi->api eq 'CAPI' ){
294                 print $gi->lib_version;
295             }
296

ISSUE TRACKER AND GIT repo

298       Is available from GitHub, see
299
300       https://github.com/maxmind/geoip-api-perl
301

SUPPORT

306       Bugs may be submitted through
307       <https://github.com/maxmind/geoip-api-perl/issues>.
308

AUTHORS

310       •   Dave Rolsky <drolsky@maxmind.com>
311
312       •   Greg Oschwald <goschwald@maxmind.com>
313

CONTRIBUTORS

315       •   asb-cpan <asb-cpan@users.noreply.github.com>
316
317       •   Boris Zentner <bzentner@maxmind.com>
318
319       •   Boris Zentner <bzm@2bz.de>
320
321       •   John SJ Anderson <genehack@genehack.org>
322
323       •   Olaf Alders <oalders@maxmind.com>
324
325       •   Philip A. Prindeville <philipp@redfish-solutions.com>
326
327       •   shawniverson <shawniverson@gmail.com>
328
329       •   Thomas J Mather <tjmather@maxmind.com>
330
331       •   Tina Mueller <TINITA@cpan.org>
332
333       •   Will Storey <will@summercat.com>
334

COPYRIGHT AND LICENSE

336       This software is copyright (c) 2002 - 2017 by MaxMind, Inc.
337
338       This is free software; you can redistribute it and/or modify it under
339       the same terms as the Perl 5 programming language system itself.
340
341
342
343perl v5.36.0                      2022-07-22                        Geo::IP(3)