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.36.0                                       2022-11-21                      GeoIP2::Database::Reader(3pm)