GeoIP2::Database::ReadUserpContributed Perl DocumGeoIP2::Database::Reader(3pm)
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:
• file
This is the path to the GeoIP2 database which you'd like to query.
The path should include the filename.
• 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:
• de - German
• 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.
• es - Spanish
• fr - French
• ja - Japanese
• pt-BR - Brazilian Portuguese
• ru - Russian
• 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:
• 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
• Dave Rolsky <drolsky@maxmind.com>
• Greg Oschwald <goschwald@maxmind.com>
• Mark Fowler <mfowler@maxmind.com>
• 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.28.1 2019-07-26 GeoIP2::Database::Reader(3pm)
Generated by dwww version 1.14 on Fri Jan 24 09:44:13 CET 2025.