1GeoIP2::WebService::CliUesnetr(3C)ontributed Perl DocumeGnetoaItPi2o:n:WebService::Client(3)
2
3
4

NAME

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

VERSION

10       version 2.006002
11

SYNOPSIS

13         use 5.008;
14
15         use GeoIP2::WebService::Client;
16
17         # This creates a Client object that can be reused across requests.
18         # Replace "42" with your account id and "abcdef123456" with your license
19         # key.
20         my $client = GeoIP2::WebService::Client->new(
21             account_id  => 42,
22             license_key => 'abcdef123456',
23         );
24
25         # Replace "insights" with the method corresponding to the web service
26         # that you are using, e.g., "country", "city".
27         my $insights = $client->insights( ip => '24.24.24.24' );
28
29         my $country = $insights->country();
30         print $country->iso_code(), "\n";
31

DESCRIPTION

33       This class provides a client API for all the GeoIP2 Precision web
34       service end points. The end points are Country, City, and Insights.
35       Each end point returns a different set of data about an IP address,
36       with Country returning the least data and Insights the most.
37
38       Each web service end point is represented by a different model class,
39       and these model classes in turn contain multiple Record classes. The
40       record classes have attributes which contain data about the IP address.
41
42       If the web service does not return a particular piece of data for an IP
43       address, the associated attribute is not populated.
44
45       The web service may not return any information for an entire record, in
46       which case all of the attributes for that record class will be empty.
47

SSL

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

USAGE

52       The basic API for this class is the same for all of the web service end
53       points. First you create a web service object with your MaxMind
54       "account_id" and "license_key", then you call the method corresponding
55       to a specific end point, passing it the IP address you want to look up.
56
57       If the request succeeds, the method call will return a model class for
58       the end point you called. This model in turn contains multiple record
59       classes, each of which represents part of the data returned by the web
60       service.
61
62       If the request fails, the client class throws an exception.
63

IP GEOLOCATION USAGE

65       IP geolocation is inherently imprecise. Locations are often near the
66       center of the population. Any location provided by a GeoIP2 web service
67       should not be used to identify a particular address or household.
68

CONSTRUCTOR

70       This class has a single constructor method:
71
72   GeoIP2::WebService::Client->new()
73       This method creates a new client object. It accepts the following
74       arguments:
75
76       •   account_id
77
78           Your MaxMind Account ID. Go to
79           <https://www.maxmind.com/en/my_license_key> to see your MaxMind
80           Account ID and license key.
81
82           Note: This replaces a previous "user_id" parameter, which is still
83           supported for backwards-compatibility, but should no longer be used
84           for new code.
85
86           This argument is required.
87
88       •   license_key
89
90           Your MaxMind license key. Go to
91           <https://www.maxmind.com/en/my_license_key> to see your MaxMind
92           Account ID and license key.
93
94           This argument is required.
95
96       •   locales
97
98           This is an array reference where each value is a string indicating
99           a locale.  This argument will be passed onto record classes to use
100           when their "name()" methods are called.
101
102           The order of the locales is significant. When a record class has
103           multiple names (country, city, etc.), its "name()" method will look
104           at each element of this array ref and return the first locale for
105           which it has a name.
106
107           Note that the only locale which is always present in the GeoIP2
108           data in "en".  If you do not include this locale, the "name()"
109           method may end up returning "undef" even when the record in
110           question has an English name.
111
112           Currently, the valid list of locale codes is:
113
114           •       de - German
115
116           •       en - English
117
118                   English names may still include accented characters if that
119                   is the accepted spelling in English. In other words,
120                   English does not mean ASCII.
121
122           •       es - Spanish
123
124           •       fr - French
125
126           •       ja - Japanese
127
128           •       pt-BR - Brazilian Portuguese
129
130           •       ru - Russian
131
132           •       zh-CN - simplified Chinese
133
134           Passing any other locale code will result in an error.
135
136           The default value for this argument is "['en']".
137
138       •   host
139
140           The hostname to make a request against. This defaults to
141           "geoip.maxmind.com". In most cases, you should not need to set this
142           explicitly.
143
144       •   ua
145
146           This argument allows you to your own LWP::UserAgent object. This is
147           useful if you cannot use a vanilla LWP object, for example if you
148           need to set proxy parameters.
149
150           This can actually be any object which supports "agent()" and
151           "request()" methods. This method will be called with an
152           HTTP::Request object as its only argument. This method must return
153           an HTTP::Response object.
154

REQUEST METHODS

156       All of the request methods accept a single argument:
157
158       •   ip
159
160           This must be a valid IPv4 or IPv6 address, or the string "me". This
161           is the address that you want to look up using the GeoIP2 web
162           service.
163
164           If you pass the string "me" then the web service returns data on
165           the client system's IP address. Note that this is the IP address
166           that the web service sees. If you are using a proxy, the web
167           service will not see the client system's actual IP address.
168
169   $client->country()
170       This method calls the GeoIP2 Precision: Country end point. It returns a
171       GeoIP2::Model::Country object.
172
173   $client->city()
174       This method calls the GeoIP2 Precision: City end point. It returns a
175       GeoIP2::Model::City object.
176
177   $client->insights()
178       This method calls the GeoIP2 Precision: Insights end point. It returns
179       a GeoIP2::Model::Insights object.
180

User-Agent HEADER

182       This module will set the User-Agent header to include the package name
183       and version of this module (or a subclass if you use one), the package
184       name and version of the user agent object, and the version of Perl.
185
186       This is set in order to help us support individual users, as well to
187       determine support policies for dependencies and Perl itself.
188

EXCEPTIONS

190       For details on the possible errors returned by the web service itself,
191       see <http://dev.maxmind.com/geoip/geoip2/web-services> for the GeoIP2
192       web service docs.
193
194       If the web service returns an explicit error document, this is thrown
195       as a GeoIP2::Error::WebService exception object. If some other sort of
196       error occurs, this is thrown as a GeoIP2::Error::HTTP object. The
197       difference is that the web service error includes an error message and
198       error code delivered by the web service. The latter is thrown when some
199       sort of unanticipated error occurs, such as the web service returning a
200       500 or an invalid error document.
201
202       If the web service returns any status code besides 200, 4xx, or 5xx,
203       this also becomes a GeoIP2::Error::HTTP object.
204
205       Finally, if the web service returns a 200 but the body is invalid, the
206       client throws a GeoIP2::Error::Generic object.
207
208       All of these error classes have an "$error->message()" method and
209       overload stringification to show that message. This means that if you
210       don't explicitly catch errors they will ultimately be sent to "STDERR"
211       with some sort of (hopefully) useful error message.
212

WHAT DATA IS RETURNED?

214       While many of the end points return the same basic records, the
215       attributes which can be populated vary between end points. In addition,
216       while an end point may offer a particular piece of data, MaxMind does
217       not always have every piece of data for any given IP address.
218
219       Because of these factors, it is possible for any end point to return a
220       record where some or all of the attributes are unpopulated.
221
222       See <http://dev.maxmind.com/geoip/geoip2/web-services> for details on
223       what data each end point may return.
224
225       The only piece of data which is always returned is the "ip_address" key
226       in the "GeoIP2::Record::Traits" record.
227
228       Every record class attribute has a corresponding predicate method so
229       you can check to see if the attribute is set.
230

SUPPORT

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

AUTHORS

236       •   Dave Rolsky <drolsky@maxmind.com>
237
238       •   Greg Oschwald <goschwald@maxmind.com>
239
240       •   Mark Fowler <mfowler@maxmind.com>
241
242       •   Olaf Alders <oalders@maxmind.com>
243
245       This software is copyright (c) 2013 - 2019 by MaxMind, Inc.
246
247       This is free software; you can redistribute it and/or modify it under
248       the same terms as the Perl 5 programming language system itself.
249
250
251
252perl v5.34.0                      2021-07-22     GeoIP2::WebService::Client(3)
Impressum