1GeoIP2::WebService::CliUesnetr(3C)ontributed Perl DocumeGnetoaItPi2o:n:WebService::Client(3)
2
6 GeoIP2::WebService::Client - Perl API for the GeoIP2 Precision web
7 services
8
10 version 2.006002
11
13 use 5.008;
14 use GeoIP2::WebService::Client;
16 # 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 # 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 my $country = $insights->country();
30 print $country->iso_code(), "\n";
31
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 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 If the web service does not return a particular piece of data for an IP
43 address, the associated attribute is not populated.
44 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
49 Requests to the GeoIP2 web service are always made with SSL.
50
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 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 If the request fails, the client class throws an exception.
63
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
70 This class has a single constructor method:
71 GeoIP2::WebService::Client->new()
73 This method creates a new client object. It accepts the following
74 arguments:
75 • account_id
77 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 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 This argument is required.
87 • license_key
89 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 This argument is required.
95 • locales
97 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 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 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 Currently, the valid list of locale codes is:
113 • de - German
115 • en - English
117 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 • es - Spanish
123 • fr - French
125 • ja - Japanese
127 • pt-BR - Brazilian Portuguese
129 • ru - Russian
131 • zh-CN - simplified Chinese
133 Passing any other locale code will result in an error.
135 The default value for this argument is "['en']".
137 • host
139 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 • ua
145 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 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
156 All of the request methods accept a single argument:
157 • ip
159 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 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 $client->country()
170 This method calls the GeoIP2 Precision: Country end point. It returns a
171 GeoIP2::Model::Country object.
172 $client->city()
174 This method calls the GeoIP2 Precision: City end point. It returns a
175 GeoIP2::Model::City object.
176 $client->insights()
178 This method calls the GeoIP2 Precision: Insights end point. It returns
179 a GeoIP2::Model::Insights object.
180
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 This is set in order to help us support individual users, as well to
187 determine support policies for dependencies and Perl itself.
188
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 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 If the web service returns any status code besides 200, 4xx, or 5xx,
203 this also becomes a GeoIP2::Error::HTTP object.
204 Finally, if the web service returns a 200 but the body is invalid, the
206 client throws a GeoIP2::Error::Generic object.
207 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
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 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 See <http://dev.maxmind.com/geoip/geoip2/web-services> for details on
223 what data each end point may return.
224 The only piece of data which is always returned is the "ip_address" key
226 in the "GeoIP2::Record::Traits" record.
227 Every record class attribute has a corresponding predicate method so
229 you can check to see if the attribute is set.
230
232 Bugs may be submitted through
233 <https://github.com/maxmind/GeoIP2-perl/issues>.
234
236 • Dave Rolsky <drolsky@maxmind.com>
237 • Greg Oschwald <goschwald@maxmind.com>
239 • Mark Fowler <mfowler@maxmind.com>
241 • Olaf Alders <oalders@maxmind.com>
243
245 This software is copyright (c) 2013 - 2019 by MaxMind, Inc.
246 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.
249perl v5.34.0 2021-07-22 GeoIP2::WebService::Client(3)