README
1NAME
2 Geo::IPfree - Look up the country of an IPv4 address
3
4SYNOPSIS
5 use Geo::IPfree;
6
7 my $geo = Geo::IPfree->new;
8 my( $code1, $name1 ) = $geo->LookUp( '200.176.3.142' );
9
10 # use memory to speed things up
11 $geo->Faster;
12
13 # lookup by hostname
14 my( $code2, $name2, $ip2 ) = $geo->LookUp( 'www.cnn.com' );
15
16DESCRIPTION
17 Geo::IPfree is a Perl module that determines the originating country of
18 an arbitrary IPv4 address. It uses a local file-based database to
19 provide basic geolocation services.
20
21 An updated version of the database can be obtained by visiting the
22 Webnet77 website: <http://software77.net/geo-ip/>.
23
24METHODS
25 new( [$db] )
26 Creates a new Geo::IPfree instance. Optionally, a database filename may
27 be passed in to load a custom data set rather than the version shipped
28 with the module.
29
30 LoadDB( $filename )
31 Load a specific database to use to look up the IP addresses.
32
33 LookUp( $ip | $hostname )
34 Given an IP address or a hostname, this function returns three things:
35
36 * The ISO 3166 country code (2 chars)
37
38 * The country name
39
40 * The IP address resolved
41
42 NB: In order to use the location services on a hostname, you will need
43 to have an internet connection to resolve a host to an IP address.
44
45 If you pass a private IP address (for example 192.168.0.1), you'll get
46 back a country code of ZZ, and country name of "Reserved for private IP
47 addresses".
48
49 Clean_Cache( )
50 Clears any cached lookup data.
51
52 Faster( )
53 Make the LookUp() faster, which is good if you're going to be calling
54 Lookup() many times. This will load the entire DB into memory and read
55 from there, not from disk (good way for slow disk or network disks), but
56 use more memory. The module "Memoize" will be enabled for some internal
57 functions too.
58
59 Note that if you call Lookup() many times, you'll end up using a lot of
60 memory anyway, so you'll be better off using a lot of memory from the
61 start by calling Faster(), and getting an improvement for all calls.
62
63 nslookup( $host, [$last_lookup] )
64 Attempts to resolve a hostname to an IP address. If it fails on the
65 first pass it will attempt to resolve the same hostname with 'www.'
66 prepended. $last_lookup is used to suppress this behavior.
67
68 ip2nb( $ip )
69 Encodes $ip into a numerical representation.
70
71 nb2ip( $number )
72 Decodes $number back to an IP address.
73
74 dec2baseX( $number )
75 Converts a base 10 (decimal) number to base 86.
76
77 baseX2dec( $number )
78 Converts a base 86 number to base 10 (decimal).
79
80VARS
81 $GeoIP->{db}
82 The database file in use.
83
84 $GeoIP->{handler}
85 The database file handler.
86
87 $GeoIP->{dbfile}
88 The database file path.
89
90 $GeoIP->{cache} BOOLEAN
91 Set/tell if the cache of LookUp() is on. If it's on it will cache
92 the last 5000 queries. Default: 1
93
94 The cache is good when you are parsing a list of IPs, generally a
95 web log. If in the log you have many lines with the same IP,
96 GEO::IPfree won't have to make a full search for each query, it will
97 cache the last 5000 different IPs. After 5000 IPs an existing IP is
98 removed from the cache and the new data is stored.
99
100 Note that the Lookup make the query without the last IP number
101 (xxx.xxx.xxx.0), then the cache for the IP 192.168.0.1 will be the
102 same for 192.168.0.2 (they are the same query, 192.168.0.0).
103
104DB FORMAT
105 The data file has a list of IP ranges & countries, for example, from
106 200.128.0.0 to 200.103.255.255 the IPs are from BR. To make a fast
107 access to the DB the format tries to use less bytes per input (block).
108 The file was in ASCII and in blocks of 7 bytes: XXnnnnn
109
110 XX -> the country code (BR,US...)
111 nnnnn -> the IP range using a base of 85 digits
112 (not in dec or hex to get space).
113
114 See CPAN for updates of the DB...
115
116NOTES
117 The file ipscountry.dat is a dedicated format for Geo::IPfree. To
118 convert it see the tool "ipct2txt.pl" in the "misc" directoy.
119
120 The module looks for "ipscountry.dat" in the following locations:
121
122 * /usr/local/share
123
124 * /usr/local/share/GeoIPfree
125
126 * through @INC (as well as all @INC directories plus "/Geo")
127
128 * from the same location that IPfree.pm was loaded
129
130SEE ALSO
131 * http://software77.net/geo-ip/
132
133AUTHOR
134 Graciliano M. P. <gm@virtuasites.com.br>
135
136MAINTAINER
137 Brian Cassidy <bricas@cpan.org>
138
139THANK YOU
140 Thanks to Laurent Destailleur (author of AWStats) that tested it on many
141 OS and fixed bugs for them, like the not portable sysread, and asked for
142 some speed improvement.
143
144COPYRIGHT & LICENSE
145 This program is free software; you can redistribute it and/or modify it
146 under the same terms as Perl itself.
147
148