GeoIP2::WebService::ClUser(Contributed Perl DocGeoIP2::WebService::Client(3pm)
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.28.1 2019-07-26 GeoIP2::WebService::Client(3pm)
Generated by dwww version 1.14 on Fri Jan 24 09:26:34 CET 2025.