IP::Country(3)

📦 version 2.28, in opensuse-leap 16.0

💅 IP::Country — the IP::Country perl module, bestie edition 🦋

okay so this is the manual page for IP::Country, and honestly? it's a whole vibe. it's a perl module that tells you what country an IP address lives in. fast. like, actually fast. strap in 💖

✨ 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

like, that's it. that's the whole usage. iconic 🎀

💜 DESCRIPTION 💜

so finding the home country of a client using only the IP address? lowkey difficult. you'd think "oh just look up the domain name" but nope — so many IP addresses aren't reverse mapped to anything useful, and the most common domain (.com) literally gives you zero help when you're hunting for a country. it's giving useless.

this module comes bundled with a database of countries where various IP addresses have been assigned. ngl, the country of assignment is probably gonna be the country associated with a large ISP rather than the client herself — but that's probably good enough for most log analysis applications, and under test it's proved to be as accurate as reverse-DNS and WHOIS lookup. slay 🔥

🫶 CONSTRUCTOR 🫶

the constructor takes no arguments. not one. zero. empty. it just works.

use IP::Country::Fast;
my $reg = IP::Country::Fast->new();

👑 OBJECT METHODS 👑

all object methods are designed to be used in an object-oriented fashion, bestie:

$result = $object->foo_method($bar,$baz);
using the module in a procedural fashion (without the arrow syntax) won't work. like, at all. i'm so serious. no cap. 💀
  • $cc = $reg->inet_atocc(HOSTNAME) — takes a string giving the name of a host, and translates that to a 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 contained within the database, returns undef. for multi-homed hosts (hosts with more than one address), the first address found is returned. and for private Internet addresses (see RFC1918), returns two asterisks '**'. kween behaviour ✨
  • $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. straightforward. demure. 🎀
  • $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. noted! 📝

⚡ 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. hello?? that's so fast 🏎️✨

out of this random selection of IP addresses, 43% had an associated country code. and the author literally asks: 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. he wants the data, bestie 💌

🙈 IP::Country::Slow warning 🙈

okay so listen. 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 if 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). pick the right one, it's not that deep 💅

IP::Country::Medium caches domain-name lookups, whereas IP::Country::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. (genuinely. he's asking. 👀)

🌈 COUNTRY CODES 🌈

you'll probably want some kind of country code -> country name conversion utility: you should use Geography::Countries from CPAN. run don't walk 🏃‍♀️💨

however, you should note the circumstances where the country code returned by IP::Country will deviate from those used by Geography::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. that's it. that's the limitation. periodt. 🫡

🔍 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 (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." — honestly? fair. respect the boundary 🧚

🍓 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. read that twice, bestie 👀

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 purposes. use of the ARIN WHOIS data for these activities is explicitly forbidden. ARIN requests to be notified of any such activities or suspicions thereof. don't do it. they will know. 💀

the information in the RIPE Database is available to the public for agreed Internet operation purposes, but is under copyright. the copyright statement is:

"Except for agreed Internet operational purposes, no part of this publication may be reproduced, stored in a retrieval system, or transmitted, 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 suspicions thereof."

Copyright (c) Latin American and Caribbean IP address Regional Registry. All rights reserved.

seems to be the RIPE copyright. "I'm sure they'll correct this in due course." — the confidence. the audacity. the hope. 😭

okay that's the whole page bestie, every single detail preserved, nothing skipped, nothing invented, mwah 💖

this has been IP::Country(3) from perl v5.42.0, dated 2015-04-14 — yeah she's a little vintage, but she still slays 🎀✨💅

📦 where this page comes from