- SEE ALSO
- COPYRIGHT AND LICENSE
IP::World - Fast IP-address to country-code translation using multiple databases
The databases that this module used to use have been discontinued in one case, and are no longer updated in the other. Therefore this module is deprecated.
This module appears to have the disadvantage that its database can only be updated by re-installing the module.
This can 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...
use IP::World; $ipw = IP::World->new($mode); $ccod = $ipw->getcc($ipad);
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.
IP::World returns the ISO-3166 country code associated with an IP4 address. This version is based on the free database from http://www.wipmania.com. Note, however, that that appears to no longer be updated. Accordingly, this module is now deprecated.
It used to also use the free GeoLite database from MaxMind but that has been discontinued (see https://blog.maxmind.com/2018/01/02/discontinuation-of-the-geolite-legacy-databases/). If you were relying on the GeoLite database you should upgrade to using GeoLite2 (see https://dev.maxmind.com/geoip/geoip2/geolite2/).
You can optionally export some constants (the IP_WORLD_* constants listed below) when you 'use' the module. For example:
use IP::World qw(IP_WORLD_TINY_PERL);
$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 is optional and selects the operating mode:
- 0 or IP_WORLD_FAST
fast, keeps data in memory (643 KB at initial release, but who cares these days?) This is the default.
- 1 or IP_WORLD_MMAP
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 or IP_WORLD_TINY
tiny, slow but saves memory by searching the database on disk using traditional C library I/O calls.
- 3 or IP_WORLD_TINY_PERL
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.
$ccod = $ipw->getcc($ipad);
$ipad should contain an IP4 address in one of two formats:
a dotted quad string like
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.
Three Perl scripts are installed with IP::World:
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
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.
Lists the database created by maint_ip_world_db.
Compares the performance of IP::World with that of similar modules.
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.
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.
See the README file in the distribution package, or let CPAN or CPANPLUS take care of installation.
Copyright (C) 2010, Craig MacKenna, with some contributions from David Cantrell
This module is free software; you may redistribute it and/or modify it under the terms of the Artistic Licence, a copy of which is included in the file ARTISTIC.txt.
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.
The WIPmania database has its own Special licence which can be found on their website at http://www.wipmania.com/terms/. In particular note that it is "Creative Commons Attribution-Noncommercial-No Derivative Works" but they also say "The Databases can be also used for any business purposes for free" provided that you don't provide an API for querying it, you don't sell derivative works, and you may have to credit them on a website.
Craig MacKenna <firstname.lastname@example.org>
David Cantrell <email@example.com>