Craig MacKenna > IP-World > IP::World

Download:
IP-World-0.37.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.37   Source  

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 checks the currency of the included database on installation, and can be scheduled to do so periodically.

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, keeps data in Mmap memory, may reduce total memory requirement of 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 using traditional C library I/O calls.
3: tiny PerlIO, slow but saves memory by searching the database on disk using Perl I/O calls. If your system doesn't support Perl I/O, 3 works like 2. If it does, performance may differ between this option and the preceding one.

getcc

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

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

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:

SCRIPTS

Three Perl scripts are installed with IP::World:

maint_ip_world_db

The application checks whether new data is available from either data source. If there is, it downloads the data and builds a new database.

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.

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 created (e.g., to restart a web server that uses the database).

The install process for IP::World runs maint_ip_world_db to ensure that the most recent data is installed.

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.

PERFORMANCE

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

  Module                       Total uS  uS/call  % not covered
  Geo::IP Standard               281982    68.84  32
  Geo::IP Memory Cache            25626     6.26  32
  IP::Country::Fast              131887    32.20  29
  IP::Country::Fast    packed    101378    24.75  29
  IP::World fast                   9311     2.27  27
  IP::World fast       packed      6965     1.70  27
  IP::World mmap                   9084     2.22  27
  IP::World mmap       packed      7023     1.71  27
  IP::World tinyC                207054    50.55  27
  IP::World tinyC      packed    210123    51.30  27
  IP::World tinyPerl             654634   159.82  27
  IP::World tinyPerl   packed    554801   135.45  27

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.

TERMINOLOGY

Our scripts ip_world_dump and ip-benchmark both use the term 'not covered' to describe IP addresses that do not map to country codes. These fall into 4 categories:

addresses that were once used but are no longer used,
addresses that are assigned for private use,
addresses that are not assigned/allocated, and
addresses that were assigned/allocated in the last month or two, that our data sources do not yet include.

INSTALLATION ^

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

COPYRIGHT AND LICENSE ^

Copyright (C) 2010, Craig MacKenna

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>

SEE ALSO ^

The function of IP-World is almost the same as that of two other CPAN modules:

IP::Country::Fast

See http://search.cpan.org/perldoc%3FIP::Country

This module appears to have the disadvantage that its database can only be updated by re-installing the module. With IP-World, MaxMind updates its GeoIP data monthly, and WIPmania updates its WorldIP data every 2 months. Such updates are automatically downloaded if you schedule maint_ip_world_db.

Geo::IP

See http://search.cpan.org/perldoc%3FGeo::IP

This uses one of the two data sources that IP-World uses. It can also use MaxMind's licensed, fee-based databases that include more data.

Unfortunately if you want this package to operate at the speeds shown in "PERFORMANCE", you have to download a C library from http://www.maxmind.com and install it from the command line. Someone should tell them about XS modules so that their whole package can be obtained from CPAN or CPANPLUS...

syntax highlighting: