Provided by: libgeoip2-perl_2.006002-2_all bug

NAME

       GeoIP2::WebService::Client - Perl API for the GeoIP2 Precision web services

VERSION

       version 2.006002

SYNOPSIS

         use 5.008;

         use GeoIP2::WebService::Client;

         # This creates a Client object that can be reused across requests.
         # Replace "42" with your account id and "abcdef123456" with your license
         # key.
         my $client = GeoIP2::WebService::Client->new(
             account_id  => 42,
             license_key => 'abcdef123456',
         );

         # Replace "insights" with the method corresponding to the web service
         # that you are using, e.g., "country", "city".
         my $insights = $client->insights( ip => '24.24.24.24' );

         my $country = $insights->country();
         print $country->iso_code(), "\n";

DESCRIPTION

       This class provides a client API for all the GeoIP2 Precision web service end points. The end points are
       Country, City, and Insights. Each end point returns a different set of data about an IP address, with
       Country returning the least data and Insights the most.

       Each web service end point is represented by a different model class, and these model classes in turn
       contain multiple Record classes. The record classes have attributes which contain data about the IP
       address.

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

       The web service may not return any information for an entire record, in which case all of the attributes
       for that record class will be empty.

SSL

       Requests to the GeoIP2 web service are always made with SSL.

USAGE

       The basic API for this class is the same for all of the web service end points. First you create a web
       service object with your MaxMind "account_id" and "license_key", then you call the method corresponding
       to a specific end point, passing it the IP address you want to look up.

       If the request succeeds, the method call will return a model class for the end point you called. This
       model in turn contains multiple record classes, each of which represents part of the data returned by the
       web service.

       If the request fails, the client 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 web service should not be used to identify a particular address or
       household.

CONSTRUCTOR

       This class has a single constructor method:

   GeoIP2::WebService::Client->new()
       This method creates a new client object. It accepts the following arguments:

       •   account_id

           Your  MaxMind  Account  ID.  Go  to  <https://www.maxmind.com/en/my_license_key>  to see your MaxMind
           Account ID and license key.

           Note: This replaces  a  previous  "user_id"  parameter,  which  is  still  supported  for  backwards-
           compatibility, but should no longer be used for new code.

           This argument is required.

       •   license_key

           Your  MaxMind  license  key.  Go  to  <https://www.maxmind.com/en/my_license_key> to see your MaxMind
           Account ID and license key.

           This argument is required.

       •   locales

           This is an array reference where each value is a string indicating a locale.  This argument  will  be
           passed onto 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']".

       •   host

           The  hostname  to  make  a  request against. This defaults to "geoip.maxmind.com". In most cases, you
           should not need to set this explicitly.

       •   ua

           This argument allows you to your own LWP::UserAgent object. This  is  useful  if  you  cannot  use  a
           vanilla LWP object, for example if you need to set proxy parameters.

           This can actually be any object which supports "agent()" and "request()" methods. This method will be
           called  with  an HTTP::Request object as its only argument. This method must return an HTTP::Response
           object.

REQUEST METHODS

       All of the request methods accept a single argument:

       •   ip

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

           If you pass the string "me" then the web service returns data on the client system's IP address. Note
           that this is the IP address that the web service sees. If you are using a proxy, the web service will
           not see the client system's actual IP address.

   $client->country()
       This method calls the GeoIP2 Precision: Country end point. It returns a GeoIP2::Model::Country object.

   $client->city()
       This method calls the GeoIP2 Precision: City end point. It returns a GeoIP2::Model::City object.

   $client->insights()
       This method calls the GeoIP2 Precision: Insights end point. It returns a GeoIP2::Model::Insights object.

User-Agent HEADER

       This  module  will set the User-Agent header to include the package name and version of this module (or a
       subclass if you use one), the package name and version of the user agent object, and the version of Perl.

       This is set in order to help us support individual users, as  well  to  determine  support  policies  for
       dependencies and Perl itself.

EXCEPTIONS

       For    details    on    the    possible    errors    returned    by   the   web   service   itself,   see
       <http://dev.maxmind.com/geoip/geoip2/web-services> for the GeoIP2 web service docs.

       If the web service returns an explicit error document, this  is  thrown  as  a  GeoIP2::Error::WebService
       exception object. If some other sort of error occurs, this is thrown as a GeoIP2::Error::HTTP object. The
       difference  is  that  the web service error includes an error message and error code delivered by the web
       service. The latter is thrown when some sort of unanticipated error  occurs,  such  as  the  web  service
       returning a 500 or an invalid error document.

       If   the  web  service  returns  any  status  code  besides  200,  4xx,  or  5xx,  this  also  becomes  a
       GeoIP2::Error::HTTP object.

       Finally,  if  the  web  service  returns  a  200  but  the  body  is  invalid,  the   client   throws   a
       GeoIP2::Error::Generic object.

       All  of  these error classes have 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 end points return the same basic records, the attributes which can be populated vary
       between end points. In addition, while an end point 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 end point 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.

       The  only  piece of data which is always returned is the "ip_address" key in the "GeoIP2::Record::Traits"
       record.

       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::WebService::Client(3pm)