GeoIP2...Client(3pm)

📦
version 2.006002 · 6 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 GeoIP2::WebService::Client — the perl client for GeoIP2 Precision 💖

okay bestie, welcome to the manual page for GeoIP2::WebService::Client, straight outta the User Contributed Perl Documentation section (3pm, obvs). This is your girl for talking to MaxMind's GeoIP2 Precision web services from Perl. Let's get into it 🫶

✨ 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";

like… look at that. three lines of setup and you're already pulling ISO codes out of an IP address. main character energy fr 💅

🌈 DESCRIPTION 🌈

This class is your whole client API for every single GeoIP2 Precision web service end point. There are three of them: Country, City, and Insights. Each one hands you back a different amount of info about an IP address — Country is the snack (least data), Insights is the whole meal (most data).

Every web service end point has its own model class, and those model classes contain a bunch of Record classes. The record classes are the ones with the attributes, and the attributes are the actual data about the IP address. it's giving nesting dolls but make it geolocation 🪆

Here's the important bit: if the web service doesn't return a particular piece of data for an IP address, the attribute for it just… doesn't get populated. And if the web service returns nothing for an entire record, then all the attributes on that record class come back empty. no cap.

🔒 SSL 🔒

Requests to the GeoIP2 web service are always made with SSL. always always. we do not play about encryption around here 🔐

💜 USAGE 💜

The basic API is literally the same across all the web service end points, so once you learn one you learned 'em all:

  1. Create a web service object with your MaxMind account_id and license_key.
  2. Call the method for the specific end point you want, passing in the IP address you're curious about.

If the request succeeds, the method call returns a model class for the end point you called. That model then contains multiple record classes, and each record class is a lil piece of the data the web service sent back.

If the request fails, the client class throws an exception. no vibes, just error. 😭

🌍 IP GEOLOCATION USAGE 🌍

Real talk bestie: IP geolocation is inherently imprecise. Locations are often near the center of the population. Any location a GeoIP2 web service gives you should not be used to identify a particular address or household. periodt. don't do it. 🚫

🎀 CONSTRUCTOR 🎀

This class has exactly one constructor method. one and done, iconic:

GeoIP2::WebService::Client->new()

This method creates a brand new client object. It accepts the following arguments:

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.

This argument is required.

  • locales — This is an array reference where each value is a string indicating a locale. This argument gets passed on to record classes so they know what to use when their name() methods are called.

The order of the locales matters. When a record class has multiple names (country, city, etc.), its name() method walks through each element of this array ref and returns the first locale it has a name for.

Note that the only locale which is always present in the GeoIP2 data is 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. we contain multitudes 💅

  • 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. trust the default, bestie 🫶
  • ua — This argument lets you pass in your own LWP::UserAgent object. Super useful if you can't use a vanilla LWP object, like when you need to set proxy parameters.

This can actually be any object that supports agent() and request() methods. request() will be called with an HTTP::Request object as its only argument, and it 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. It's the address you want to look up using the GeoIP2 web service.

If you pass the string me, the web service returns data on the client system's IP address. Heads up though: this is the IP address that the web service sees. If you're using a proxy, the web service will not see the client system's actual IP address. sneaky little middleman situation 🙈

$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 sets 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.

Why? To help us support individual users, and to figure out support policies for dependencies and Perl itself. it's giving "we're keeping receipts but in a helpful way" 📝✨

💀 EXCEPTIONS 💀

For the deets on possible errors the web service itself returns, go look at <http://dev.maxmind.com/geoip/geoip2/web-services> for the GeoIP2 web service docs.

If the web service returns an explicit error document, that gets thrown as a GeoIP2::Error::WebService exception object. If some other sort of error happens, that gets thrown as a GeoIP2::Error::HTTP object.

The difference? The web service error comes with an error message and error code delivered by the web service. The GeoIP2::Error::HTTP one gets thrown when something unanticipated goes down — like the web service returning a 500, or an invalid error document.

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

And 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. Which means if you don't explicitly catch your errors, they'll ultimately be sent to STDERR with some sort of (hopefully) useful error message. not me letting errors just vibe into stderr 🙈

👑 WHAT DATA IS RETURNED? 👑

Okay so, while a lot of the end points return the same basic records, the attributes that can actually be populated vary between end points. And on top of that — even when an end point offers a particular piece of data, MaxMind doesn't always have every piece of data for any given IP address.

Because of these factors, it's completely possible for any end point to return a record where some or all of the attributes are unpopulated. empty records are just a thing that happens, don't panic.

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. that one's the ride-or-die 💖

Every record class attribute has a corresponding predicate method, so you can check whether the attribute is set. use it. love it. predicate methods are your besties.

🧚 SUPPORT 🧚

Bugs may be submitted through <https://github.com/maxmind/GeoIP2-perl/issues>. come through, drop an issue, we'll look at it 🫶

⭐ AUTHORS ⭐

  • Dave Rolsky <drolsky@maxmind.com>
  • Greg Oschwald <goschwald@maxmind.com>
  • Mark Fowler <mfowler@maxmind.com>
  • Olaf Alders <oalders@maxmind.com>

the whole squad. legends only 👑

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. slay, open source 💅

and that's the whole page bestie!! this was perl v5.36.0, dated 2022-11-21, filed under GeoIP2...Client(3pm) — go look up some IPs, you got this 🌸🦋💜

📦 where this page comes from