Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Geo::IP(3)	      User Contributed Perl Documentation	    Geo::IP(3)

NAME
       Geo::IP - Look up location and network information by IP	Address

VERSION
       version 1.50

SYNOPSIS
	 use Geo::IP;
	 my $gi	= Geo::IP->new(GEOIP_MEMORY_CACHE);
	 # look	up IP address '24.24.24.24'
	 # returns undef if country is unallocated, or not defined in our database
	 my $country = $gi->country_code_by_addr('24.24.24.24');
	 $country = $gi->country_code_by_name('yahoo.com');
	 # $country is equal to	"US"

	 use Geo::IP;
	 my $gi	= Geo::IP->open("/usr/local/share/GeoIP/GeoIPCity.dat",	GEOIP_STANDARD);
	 my $record = $gi->record_by_addr('24.24.24.24');
	 print $record->country_code,
	       $record->country_code3,
	       $record->country_name,
	       $record->region,
	       $record->region_name,
	       $record->city,
	       $record->postal_code,
	       $record->latitude,
	       $record->longitude,
	       $record->time_zone,
	       $record->area_code,
	       $record->continent_code,
	       $record->metro_code;

	 # the IPv6 support is currently only avail if you use the CAPI	which is much
	 # faster anyway. ie: print Geo::IP->api equals	to 'CAPI'
	 use Socket;
	 use Socket6;
	 use Geo::IP;
	 my $g = Geo::IP->open('/usr/local/share/GeoIP/GeoIPv6.dat') or	die;
	 print $g->country_code_by_ipnum_v6(inet_pton AF_INET6,	'::24.24.24.24');
	 print $g->country_code_by_addr_v6('2a02:e88::');

DESCRIPTION
       This module uses	the GeoIP Legacy file based database.  This database
       simply contains IP blocks as keys, and countries	as values. This
       database	should be more complete	and accurate than reverse DNS lookups.

       This module can be used to automatically	select the geographically
       closest mirror, to analyze your web server logs to determine the
       countries of your visitors, for credit card fraud detection, and	for
       software	export controls.

IP GEOLOCATION USAGE
       IP geolocation is inherently imprecise. Locations are often near	the
       center of the population. Any location provided by a GeoIP database or
       web service should not be used to identify a particular address or
       household.

IP ADDRESS TO COUNTRY DATABASES
       Free monthly updates to the database are	available from

	 http://dev.maxmind.com/geoip/geolite

       This free database is similar to	the database contained in IP::Country,
       as well as many paid databases. It uses ARIN, RIPE, APNIC, and LACNIC
       whois to	obtain the IP->Country mappings.

       If you require greater accuracy,	MaxMind	offers a database on a paid
       subscription basis.  Also included with this is a service that updates
       your database automatically each	month, by running a program called
       geoipupdate included with the C API from	a cronjob.  For	more details
       on the differences between the free and paid databases, see:

       http://www.maxmind.com/en/geolocation_landing

       Do not miss the city database, described	in Geo::IP::Record

       Make sure to use	the geolite-mirror-simple.pl script from the example
       directory to stay current with the databases.

BENCHMARK the lookups are fast.	This is	my laptop ( examples/benchmark.pl ):
	 Benchmark: running city_mem, city_std,	country_mem, country_std, country_v6_mem, country_v6_std, isp_mem, isp_std for at least	10 CPU seconds...
	   city_mem: 10.3121 wallclock secs (10.30 usr +  0.01 sys = 10.31 CPU)	@ 387271.48/s (n=3992769)
	   city_std: 10.0658 wallclock secs ( 2.86 usr +  7.17 sys = 10.03 CPU)	@ 54392.62/s (n=545558)
	 country_mem: 10.1772 wallclock	secs (10.16 usr	+  0.00	sys = 10.16 CPU) @ 1077507.97/s	(n=10947481)
	 country_std: 10.1432 wallclock	secs ( 2.30 usr	+  7.85	sys = 10.15 CPU) @ 83629.56/s (n=848840)
	 country_v6_mem: 10.2579 wallclock secs	(10.25 usr + -0.00 sys = 10.25 CPU) @ 365997.37/s (n=3751473)
	 country_v6_std: 10.8541 wallclock secs	( 1.77 usr +  9.07 sys = 10.84 CPU) @ 10110.42/s (n=109597)
	    isp_mem: 10.147 wallclock secs (10.13 usr +	 0.01 sys = 10.14 CPU) @ 590109.66/s (n=5983712)
	    isp_std: 10.0484 wallclock secs ( 2.71 usr +  7.33 sys = 10.04 CPU)	@ 73186.35/s (n=734791)

CLASS METHODS
       $gi = Geo::IP->new( $flags );
	   Constructs a	new Geo::IP object with	the default database located
	   inside your system's	datadir, typically
	   /usr/local/share/GeoIP/GeoIP.dat.

	   Flags can be	set to either GEOIP_STANDARD, or for faster
	   performance (at a cost of using more	memory), GEOIP_MEMORY_CACHE.
	   When	using memory cache you can force a reload if the file is
	   updated by setting GEOIP_CHECK_CACHE.  GEOIP_INDEX_CACHE caches the
	   most	frequently accessed index portion of the database, resulting
	   in faster lookups than GEOIP_STANDARD, but less memory usage	than
	   GEOIP_MEMORY_CACHE -	useful for larger databases such as GeoIP
	   Legacy Organization and GeoIP City. Note, for GeoIP Country,	Region
	   and Netspeed	databases, GEOIP_INDEX_CACHE is	equivalent to
	   GEOIP_MEMORY_CACHE.

	   Prior to geoip-api version 1.6.3, the C API would leak diagnostic
	   messages onto stderr	unconditionally. From Geo::IP v1.44 onwards,
	   the flag squelching this behavior (GEOIP_SILENCE) is	implicitly
	   added to the	flags passed in	new(), open(), and open_type().

	   To combine flags, use the bitwise OR	operator, |.  For example, to
	   cache the database in memory, but check for an updated GeoIP.dat
	   file, use: Geo::IP->new( GEOIP_MEMORY_CACHE | GEOIP_CHECK_CACHE );

       $gi = Geo::IP->open( $database_filename,	$flags );
	   Constructs a	new Geo::IP object with	the database located at
	   $database_filename.

       $gi = Geo::IP->open_type( $database_type, $flags	);
	   Constructs a	new Geo::IP object with	the $database_type database
	   located in the standard location.  For example

	     $gi = Geo::IP->open_type( GEOIP_CITY_EDITION_REV1 , GEOIP_STANDARD	);

	   opens the database file in the standard location for	GeoIP Legacy
	   City, typically /usr/local/share/GeoIP/GeoIPCity.dat.

OBJECT METHODS
       $code = $gi->country_code_by_addr( $ipaddr );
	   Returns the ISO 3166	country	code for an IP address.

       $code = $gi->country_code_by_name( $hostname );
	   Returns the ISO 3166	country	code for a hostname.

       $code = $gi->country_code3_by_addr( $ipaddr );
	   Returns the 3 letter	country	code for an IP address.

       $code = $gi->country_code3_by_name( $hostname );
	   Returns the 3 letter	country	code for a hostname.

       $name = $gi->country_name_by_addr( $ipaddr );
	   Returns the full country name for an	IP address.

       $name = $gi->country_name_by_name( $hostname );
	   Returns the full country name for a hostname.

       $r = $gi->record_by_addr( $ipaddr );
	   Returns a Geo::IP::Record object containing city location for an IP
	   address.

       $r = $gi->record_by_name( $hostname );
	   Returns a Geo::IP::Record object containing city location for a
	   hostname.

       $org = $gi->org_by_addr(	$ipaddr	); deprecated use "name_by_addr"
       instead.
	   Returns the Organization, ISP name or Domain	Name for an IP
	   address.

       $org = $gi->org_by_name(	$hostname );  deprecated use "name_by_name"
       instead.
	   Returns the Organization, ISP name or Domain	Name for a hostname.

       $info = $gi->database_info;
	   Returns database string, includes version, date, build number and
	   copyright notice.

       $old_charset = $gi->set_charset(	$charset );
	   Set the charset for the city	name - defaults	to
	   GEOIP_CHARSET_ISO_8859_1.  To set UTF8, pass	GEOIP_CHARSET_UTF8 to
	   set_charset.	 For perl >= 5.008 the utf8 flag is honored.

       $charset	= $gi->charset;
	   Gets	the currently used charset.

       ( $country, $region ) = $gi->region_by_addr('24.24.24.24');
	   Returns a list containing country and region. If region and/or
	   country is unknown, undef is	returned. Sure this works only for
	   region databases.

       ( $country, $region ) = $gi->region_by_name('www.xyz.com');
	   Returns a list containing country and region. If region and/or
	   country is unknown, undef is	returned. Sure this works only for
	   region databases.

       $netmask	= $gi->last_netmask;
	   Gets	netmask	of network block from last lookup.

       $gi->netmask(12);
	   Sets	netmask	for the	last lookup

       my ( $from, $to ) = $gi->range_by_ip('24.24.24.24');
	   Returns the start and end of	the current network block. The method
	   tries to join several continuous netblocks.

       $api = $gi->api or $api = Geo::IP->api
	   Returns the currently used API.

	     # prints either CAPI or PurePerl
	     print Geo::IP->api;

       $continent = $gi->continent_code_by_country_code('US');
	   Returns the continent code by country code.

       $dbe = $gi->database_edition
	   Returns the database_edition	of the currently opened	database.

	     if	( $gi->database_edition	== GEOIP_COUNTRY_EDITION ){
	       ...
	     }

       $isp = $gi->isp_by_addr('24.24.24.24');
	   Returns the isp for 24.24.24.24

       $isp = $gi->isp_by_name('www.maxmind.com');
	   Returns the isp for www.something.de

       my $time_zone = $gi->time_zone('US', 'AZ');
	   Returns the time zone for country/region.

	     # undef
	     print  $gi->time_zone('US', '');

	     # America/Phoenix
	     print  $gi->time_zone('US', 'AZ');

	     # Europe/Berlin
	     print  $gi->time_zone('DE', '00');

	     # Europe/Berlin
	     print  $gi->time_zone('DE', '');

       $id = $gi->id_by_addr('24.24.24.24');
	   Returns the country_id for 24.24.24.24. The country_id might	be
	   useful as array index. 0 is unknown.

       $id = $gi->id_by_name('www.maxmind.com');
	   Returns the country_id for www.maxmind.com. The country_id might be
	   useful as array index. 0 is unknown.

       $cc = $gi->country_code3_by_addr_v6('::24.24.24.24');
       $cc = $gi->country_code3_by_name_v6('ipv6.google.com');
       $cc = $gi->country_code_by_addr_v6('2a02:ea0::');
       $cc = $gi->country_code_by_ipnum_v6($ipnum);
	     use Socket;
	     use Socket6;
	     use Geo::IP;
	     my	$g = Geo::IP->open('/usr/local/share/GeoIP/GeoIPv6.dat') or die;
	     print $g->country_code_by_ipnum_v6(inet_pton AF_INET6, '::24.24.24.24');

       $cc = $gi->country_code_by_name_v6('ipv6.google.com');
       name_by_addr
	   Returns the Organization, ISP name or Domain	Name for a IP address.

       name_by_addr_v6
	   Returns the Organization, ISP name or Domain	Name for an IPv6
	   address.

       name_by_ipnum_v6
	   Returns the Organization, ISP name or Domain	Name for an ipnum.

       name_by_name
	   Returns the Organization, ISP name or Domain	Name for a hostname.

       name_by_name_v6
	   Returns the Organization, ISP name or Domain	Name for a hostname.

       org_by_addr_v6 deprecated use "name_by_addr_v6"
	   Returns the Organization, ISP name or Domain	Name for an IPv6
	   address.

       org_by_name_v6  deprecated use "name_by_name_v6"
	   Returns the Organization, ISP name or Domain	Name for a hostname.

       teredo
	   Returns the current setting for teredo.

       enable_teredo
	   Enable / disable teredo

	     $gi->enable_teredo(1); # enable
	     $gi->enable_teredo(0); # disable

       lib_version
	     if	( $gi->api eq 'CAPI' ){
		 print $gi->lib_version;
	     }

ISSUE TRACKER AND GIT repo
       Is available from GitHub, see

       https://github.com/maxmind/geoip-api-perl

SEE ALSO
       GeoIP2 -	database reader	for the	GeoIP2 format.

AUTHORS
       o   Dave	Rolsky <drolsky@maxmind.com>

       o   Greg	Oschwald <goschwald@maxmind.com>

CONTRIBUTORS
       o   asb-cpan <asb-cpan@users.noreply.github.com>

       o   Boris Zentner <bzentner@maxmind.com>

       o   Boris Zentner <bzm@2bz.de>

       o   John	SJ Anderson <genehack@genehack.org>

       o   Olaf	Alders <oalders@maxmind.com>

       o   Philip A. Prindeville <philipp@redfish-solutions.com>

       o   shawniverson	<shawniverson@gmail.com>

       o   Thomas J Mather <tjmather@maxmind.com>

       o   Tina	Mueller	<TINITA@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2016 by MaxMind, Inc.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2016-07-21			    Geo::IP(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | IP GEOLOCATION USAGE | IP ADDRESS TO COUNTRY DATABASES | BENCHMARK the lookups are fast. This is my laptop ( examples/benchmark.pl ): | CLASS METHODS | OBJECT METHODS | ISSUE TRACKER AND GIT repo | SEE ALSO | AUTHORS | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Geo::IP&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help