IP::Country
IP::Country(3) User Contributed Perl Documentation IP::Country(3)
NAME
IP::Country - fast lookup of country codes from IP addresses
SYNOPSIS
use IP::Country::Fast;
my $reg = IP::Country::Fast->new();
print $reg->inet_atocc(’212.67.197.128’) ."\n";
print $reg->inet_atocc(’www.slashdot.org’) ."\n";
print $reg->db_time() ."\n"; # revision date
DESCRIPTION
Finding the home country of a client using only the IP address can be
difficult. Looking up the domain name associated with that address
can provide some help, but many IP address are not reverse mapped to
any useful domain, and the most common domain (.com) offers no help
when looking for country.
This module comes bundled with a database of countries where various
IP addresses have been assigned. Although the country of assignment
will probably be the country associated with a large ISP rather than
the client herself, this is probably good enough for most log analysis
applications, and under test has proved to be as accurate as reverse-
DNS and WHOIS lookup.
CONSTRUCTOR
The constructor takes no arguments.
use IP::Country::Fast;
my $reg = IP::Country::Fast->new();
OBJECT METHODS
All object methods are designed to be used in an object-oriented fash-
ion.
$result = $object->foo_method($bar,$baz);
Using the module in a procedural fashion (without the arrow syntax)
won’t work.
$cc = $reg->inet_atocc(HOSTNAME)
Takes a string giving the name of a host, and translates that to
an two-letter country code. Takes arguments of both the
’rtfm.mit.edu’ type and ’18.181.0.24’. If the host name cannot be
resolved, returns undef. If the resolved IP address is not con-
tained within the database, returns undef. For multi-homed hosts
(hosts with more than one address), the first address found is
returned. For private Internet addresses (see RFC1918), returns
two asterisks ’**’.
$cc = $reg->inet_ntocc(IP_ADDRESS)
Takes a string (an opaque string as returned by
Socket::inet_aton()) and translates it into a two-letter country
code. If the IP address is not contained within the database,
returns undef.
$cc = $reg->db_time()
Returns the creation date of the database, measured as number of
seconds since the Unix epoch (00:00:00 GMT, January 1, 1970).
Suitable for feeding to "gmtime" and "localtime". When used with
IP::Country::Medium or Slow objects, returns zero.
PERFORMANCE
With a random selection of 65,000 IP addresses, the module can look up
over 15,000 IP addresses per second on a 730MHz PIII (Coppermine) and
over 25,000 IP addresses per second on a 1.3GHz Athlon. Out of this
random selection of IP addresses, 43% had an associated country code.
Please let me know if you’ve run this against a set of ’real’ IP
addresses from your log files, and have details of the proportion of
IPs that had associated country codes.
IP::Country::Slow warning
During tests of this module, it was found that there was no measurable
advantage in using this module in preference to IP::Country::Medium or
IP::Country::Fast. You should use IP::Country::Medium is the majority
of your lookups are of the form ’rtfm.mit.edu’ (domain names), and
IP::Country::Fast if the majority of your lookups are of the form
’18.181.0.24’ (IP addresses).
IP::Country::Medium caches domain-name lookups, whereas IP::Coun-
try::Fast does not.
It is *very* rare for a domain-name lookup to differ from the database
used by IP::Country::Fast. Thus, there is no good reason to prefer a
slow domain-name lookup to a fast database lookup. Nor is there any
significant difference in coverage between the domain-name system and
database. If you can find a real reason to use IP::Country::Slow, let
me know.
COUNTRY CODES
You’ll probably want some kind of country code -> country name conver-
sion utility: you should use Geography::Countries from CPAN.
However, you should note the circumstances where the country code
returned by IP::Country will deviate from those used by Geogra-
phy::Countries:
AP - non-specific Asia-Pacific location
CS - Czechoslovakia (former)
EU - non-specific European Union location
FX - France, Metropolitan
PS - Palestinian Territory, Occupied
** - intranet address
undef - not in database
BUGS/LIMITATIONS
Only works with IPv4 addresses and ASCII hostnames.
SEE ALSO
IP::Country::Fast - recommended for lookups of hostnames which are
mostly in the dotted-quad form (’213.45.67.89’).
IP::Country::Medium - recommended for lookups of hostnames which are
mostly in the domain-name form (’www.yahoo.com’). Caches domain-name
lookups.
IP::Country::Slow - NOT RECOMMENDED. Only included for completeness.
Prefers domain-name lookups to database lookups, which is an expensive
strategy of no benefit.
Geo::IP - wrapper around the geoip C libraries. Less portable. Not
measurably faster than these native Perl modules. Paid subscription
required for database updates.
<http://www.apnic.net> - Asia pacific
<http://www.ripe.net> - Europe
<http://www.arin.net> - North America
<http://www.lacnic.net> - Latin America
<http://www.afrinic.net> - Africa and Indian Ocean
COPYRIGHT
Copyright (C) 2002-2005 Nigel Wetters Gourlay. All Rights Reserved.
NO WARRANTY. This module is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
Some parts of this software distribution are derived from the APNIC,
LACNIC, ARIN, AFRINIC and RIPE databases (copyright details below). I
am not a lawyer, so please direct questions about the RIR’s licenses
to them, not me.
APNIC conditions of use
The files are freely available for download and use on the condition
that APNIC will not be held responsible for any loss or damage arising
from the application of the information contained in these reports.
APNIC endeavours to the best of its ability to ensure the accuracy of
these reports; however, APNIC makes no guarantee in this regard.
In particular, it should be noted that these reports seek to indicate
the country where resources were first allocated or assigned. It is
not intended that these reports be considered as an authoritative
statement of the location in which any specific resource may currently
be in use.
ARIN database copyright
Copyright (c) American Registry for Internet Numbers. All rights
reserved.
The ARIN WHOIS data is for Internet operational or technical research
purposes pertaining to Internet operations only. It may not be used
for advertising, direct marketing, marketing research, or similar pur-
poses. Use of the ARIN WHOIS data for these activities is explicitly
forbidden. ARIN requests to be notified of any such activities or
suspicions thereof.
RIPE database copyright
The information in the RIPE Database is available to the public for
agreed Internet operation purposes, but is under copyright. The copy-
right statement is:
"Except for agreed Internet operational purposes, no part of this pub-
lication may be reproduced, stored in a retrieval system, or transmit-
ted, in any form or by any means, electronic, mechanical, recording,
or otherwise, without prior permission of the RIPE NCC on behalf of
the copyright holders. Any use of this material to target advertising
or similar activities is explicitly forbidden and may be prosecuted.
The RIPE NCC requests to be notified of any such activities or suspi-
cions thereof."
LACNIC database copyright
Copyright (c) Latin American and Caribbean IP address Regional Reg-
istry. All rights reserved.
AFRINIC copyright
Seems to be the RIPE copyright. I’m sure they’ll correct this in due
course.
perl v5.8.8 2009-01-01 IP::Country(3)
