NAME

IP::World - Fast IP-address to country-code translation using multiple databases

SYNOPSIS

 use IP::World;
 $ipw = IP::World->new($mode);
 $ccod = $ipw->getcc($ipad);

DESCRIPTION

IP::World returns the ISO-3166 country code associated with an IP4 address. This version is based on two free databases from http://www.wipmania.com and http://www.maxmind.com. An included application downloads the current version of the databases on installation, and can be scheduled to do so again whenever it's necessary.

The author uses this package for customizing served web pages to the location of the visitor, particularly to quote prices of items for sale in the visitor's currency. Also for server log analysis.

METHODS

new

  $ipw = IP::World->new($mode);

In object-oriented terms, this is a constructor. It returns a scalar object that's used in calling the getcc method as described below.

$mode selects the operating mode:

0: fast, keeps data in memory (643 KB at initial release, but who cares these days?)
1: Mmap, may save memory among sibling processes. If your system doesn't support Mmap, 1 operates like 0.
2: tiny, slow but saves memory by searching the database on disk

getcc

  $ccod = $ipw->getcc($ipad);

$ipad should contain an IP4 address in one of two formats:

a dotted quad string like '13.117.255.3'
a 4-byte packed binary string produced by inet_aton or pack('C4', four values 0-255)

The return value from getcc will always be a 2-character string. For most IP addresses this will be one of the codes defined in the ISO-3166 standard. You can see these codes on http://www.iso.org/iso/english_country_names_and_code_elements.

Two return values indicate problems in determining the country code:

'**' indicates that $ipad was not in either of the two formats described above.
'??' indicates that the database doesn't include a mapping for the IP address.

SCRIPTS

Three Perl scripts are installed along with IP::World:

maint_ip_world_db

The application checks whether new data is available from either data source, and downloads it if so.

You can run this manually to check for a new database, or (on a server or other 24/7 system) you can schedule it for automatic execution at a non-busy time each day.

In either case you should run maint_ip_world_db with privilege to rewrite the database file. For Unix/Linux systems this means running it as root, such as by entering the command sudo maint_ip_world_db.

During installation, you will be asked if a command should be executed by maint_ip_world_db when a new database has been downloaded (e.g., to restart a web server that uses the database).

The install process for IP::World runs maint_ip_world_db to create the initial database in the right binary-data format for your system.

ip_world_dump

Lists the database created by maint_ip_world_db.

ip_cc_benchmark

Compares the performance of IP::World with that of similar modules. See Performance.

PERFORMANCE

ip-benchmark showed the following results in one run on the author's server:

  Module                   Total uS  uS/call  % unknown
  IP::Country:Fast           130558    31.88  30
  IP::Country:Fast packed    100448    24.52  30
  Geo::IP Standard            57023    13.92  32
  Geo::IP Memory Cache        23914     5.84  32
  IP::World fast               8748     2.14  28
  IP::World fast   packed      6961     1.70  28
  IP::World mmap               9007     2.20  28
  IP::World mmap   packed      7213     1.76  28
  IP::World tiny             523165   127.73  28
  IP::World tiny   packed    522045   127.45  28

packed indicates conversion of a packed 32-bit IP address rather than a text address. ip-benchmark uses the same set of random IP addresses for all of the modules in each execution.

INSTALLATION

See the README file in the distribution package, or let CPAN or CPANPLUS take care of installation.

COPYRIGHT AND LICENSE

This module is free software; you may redistribute it and/or modify it under the same terms as Perl 5.10.1. For more details, see the full text of the licenses at http://www.perlfoundation.org/artistic_license_1_0 and http://www.gnu.org/licenses/gpl-2.0.html

This program is distributed in the hope that it will be useful, but it is provided 'as is' and without any express or implied warranties. For details, see the full text of the licenses at the above URLs.

AUTHOR

Craig MacKenna <craig@animalhead.com>