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

FreeBSD Manual Pages

  
 
  

home | help
GeoIP2::Database::ReadUser)Contributed Perl DocumenGeoIP2::Database::Reader(3)

NAME
       GeoIP2::Database::Reader	- Perl API for GeoIP2 databases

VERSION
       version 2.006002

SYNOPSIS
	 use 5.008;

	 use GeoIP2::Database::Reader;

	 my $reader = GeoIP2::Database::Reader->new(
	     file    =>	'/path/to/database',  #	e.g. /home/maxmind/db/GeoIP2-Country.mmdb
	     locales =>	[ 'en',	'de', ]
	 );

	 my $city = $reader->city( ip => '24.24.24.24' );
	 my $country = $city->country();
	 print $country->iso_code(), "\n";

DESCRIPTION
       This class provides a reader API	for all	GeoIP2 databases. Each method
       returns a different model class.

       If the database does not	return a particular piece of data for an IP
       address,	the associated attribute is not	populated.

USAGE
       The basic API for this class is the same	for all	database types.	 First
       you create a database reader object with	your "file" and	"locale"
       params.	Then you call the method corresponding to your database	type,
       passing it the IP address you want to look up.

       If the request succeeds,	the method call	will return a model class for
       the method point	you called.

       If the database cannot be read, the reader class	throws an exception.

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

CONSTRUCTOR
       This class has a	single constructor method:

   GeoIP2::Database::Reader->new()
       This method creates a new object. It accepts the	following arguments:

       o   file

	   This	is the path to the GeoIP2 database which you'd like to query.
	   The path should include the filename.

       o   locales

	   This	is an array reference where each value is a string indicating
	   a locale.  This argument will be passed on to record	classes	to use
	   when	their "name()" methods are called.

	   The order of	the locales is significant. When a record class	has
	   multiple names (country, city, etc.), its "name()" method will look
	   at each element of this array ref and return	the first locale for
	   which it has	a name.

	   Note	that the only locale which is always present in	the GeoIP2
	   data	in "en".  If you do not	include	this locale, the "name()"
	   method may end up returning "undef" even when the record in
	   question has	an English name.

	   Currently, the valid	list of	locale codes is:

	   o	   de -	German

	   o	   en -	English

		   English names may still include accented characters if that
		   is the accepted spelling in English.	In other words,
		   English does	not mean ASCII.

	   o	   es -	Spanish

	   o	   fr -	French

	   o	   ja -	Japanese

	   o	   pt-BR - Brazilian Portuguese

	   o	   ru -	Russian

	   o	   zh-CN - simplified Chinese

	   Passing any other locale code will result in	an error.

	   The default value for this argument is "['en']".

REQUEST	METHODS
       All of the request methods accept a single argument:

       o   ip

	   This	must be	a valid	IPv4 or	IPv6 address. This is the address that
	   you want to look up using the GeoIP2	web service.

	   Unlike the web service client class,	you cannot pass	the string
	   "me"	as your	ip address.

   $reader->asn()
       This method returns a GeoIP2::Model::ASN	object.

   $reader->connection_type()
       This method returns a GeoIP2::Model::ConnectionType object.

   $reader->country()
       This method returns a GeoIP2::Model::Country object.

   $reader->city()
       This method returns a GeoIP2::Model::City object.

   $reader->domain()
       This method returns a GeoIP2::Model::Domain object.

   $reader->isp()
       This method returns a GeoIP2::Model::ISP	object.

   $reader->enterprise()
       This method returns a GeoIP2::Model::Enterprise object.

   $reader->anonymous_ip()
       This method returns a GeoIP2::Model::AnonymousIP	object.

OTHER METHODS
   $reader->metadata()
       This method returns a MaxMind::DB::Metadata object containing
       information about the database.

EXCEPTIONS
       In the case of a	fatal error, the reader	will throw a
       GeoIP2::Error::Generic or GeoIP2::Error::IPAddressNotFound exception
       object.

       This error class	has an "$error->message()" method and overload
       stringification to show that message. This means	that if	you don't
       explicitly catch	errors they will ultimately be sent to "STDERR"	with
       some sort of (hopefully)	useful error message.

WHAT DATA IS RETURNED?
       While many of the databases return the same basic records, the
       attributes which	can be populated vary between model classes. In
       addition, while a database may offer a particular piece of data,
       MaxMind does not	always have every piece	of data	for any	given IP
       address.

       Because of these	factors, it is possible	for any	model class to return
       a record	where some or all of the attributes are	unpopulated.

       See <http://dev.maxmind.com/geoip/geoip2/web-services> for details on
       what data each end point	may return.

       Every record class attribute has	a corresponding	predicate method so
       you can check to	see if the attribute is	set.

SUPPORT
       Bugs may	be submitted through
       <https://github.com/maxmind/GeoIP2-perl/issues>.

AUTHORS
       o   Dave	Rolsky <drolsky@maxmind.com>

       o   Greg	Oschwald <goschwald@maxmind.com>

       o   Mark	Fowler <mfowler@maxmind.com>

       o   Olaf	Alders <oalders@maxmind.com>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2013 - 2019 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.32.0			  2019-06-18	   GeoIP2::Database::Reader(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | USAGE | IP GEOLOCATION USAGE | CONSTRUCTOR | REQUEST METHODS | OTHER METHODS | EXCEPTIONS | WHAT DATA IS RETURNED? | SUPPORT | AUTHORS | COPYRIGHT AND LICENSE

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

home | help