GeoIP2...Reader(3pm)

💖 GeoIP2::Database::Reader 💖

okay so bestie, welcome to GeoIP2::Database::Reader — the Perl API for GeoIP2 databases. yes she's a Perl module, yes she's iconic, and yes we're gonna get you fluent in her by the end of this page. let's go 🦋

---

✨ VERSION ✨

version 2.006002 — that's the one, no cap 💅

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready:

use 5.008;

use GeoIP2::Database::Reader;

my $reader = GeoIP2::Database::Reader->new(
    file    => '/path/to/database',  # e.g. /home/maxmind/db/GeoIP2-Country.mmdb
    locales => [ 'en', 'de', ]
);

my $city = $reader->city( ip => '24.24.24.24' );
my $country = $city->country();
print $country->iso_code(), "\n";

like… look at her. building a reader, asking about a city, printing an ISO code. main character energy fr fr 👑

---

🎀 DESCRIPTION 🎀

This class provides a reader API for all GeoIP2 databases. Each method returns a different model class. it's giving "one reader to rule them all" iykyk.

And lowkey important: if the database doesn't return a particular piece of data for an IP address, the associated attribute is not populated. no fake data, no guessing, just silence. respect 💜

---

🌈 USAGE 🌈

The basic API for this class is the same for all database types. So:

1. you create a database reader object with your file and locale params
2. then you call the method corresponding to your database type, passing it the IP address you want to look up

If the request succeeds, the method call will return a model class for the method point you called. slay ✨

If the database cannot be read, the reader class throws an exception. dramatic? yes. correct? also yes. 💀

---

🌍 IP GEOLOCATION USAGE 🌍

okay real talk for a sec because this part actually matters:

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

bestie. do NOT use this to find a specific person's house. that's not the vibe and it's not what the data can do. periodt 🙈

---

🧚 CONSTRUCTOR 🧚

This class has a single constructor method:

GeoIP2::Database::Reader->new()

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

• file — This is the path to the GeoIP2 database which you'd like to query. The path should include the filename. don't be shy, give her the whole path 💖
• locales — This is an array reference where each value is a string indicating a locale. This argument will be passed on to 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. first come, first served, bestie 🎀

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. so… include en. just do it. 🙏

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. she's multilingual, she contains 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. no improvising bestie, the list is the list 🚫

The default value for this argument is ['en'].

---

🔥 REQUEST METHODS 🔥

All of the request methods accept a single argument:

• ip — This must be a valid IPv4 or IPv6 address. This is the address that you want to look up using the GeoIP2 web service.

Unlike the web service client class, you cannot pass the string me as your ip address. sorry girl, no "me" here, this is a local database, she doesn't know who you are 😭

---

$reader->asn()

This method returns a GeoIP2::Model::ASN object.

$reader->connection_type()

This method returns a GeoIP2::Model::ConnectionType object.

$reader->country()

This method returns a GeoIP2::Model::Country object.

$reader->city()

This method returns a GeoIP2::Model::City object.

$reader->domain()

This method returns a GeoIP2::Model::Domain object.

$reader->isp()

This method returns a GeoIP2::Model::ISP object.

$reader->enterprise()

This method returns a GeoIP2::Model::Enterprise object.

$reader->anonymous_ip()

This method returns a GeoIP2::Model::AnonymousIP object.

---

💅 OTHER METHODS 💅

$reader->metadata()

This method returns a MaxMind::DB::Metadata object containing information about the database. she tells you about herself, we love a self-aware queen 👑

---

😭 EXCEPTIONS 😭

In the case of a fatal error, the reader will throw a GeoIP2::Error::Generic or GeoIP2::Error::IPAddressNotFound exception object.

This error class has 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. (hopefully. 💀)

---

🍓 WHAT DATA IS RETURNED? 🍓

While many of the databases return the same basic records, the attributes which can be populated vary between model classes. In addition, while a database 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 model class to return a record where some or all of the attributes are unpopulated. not a bug, just reality bestie 🌸

See <http://dev.maxmind.com/geoip/geoip2/web-services> for details on what data each end point may return.

Every record class attribute has a corresponding predicate method so you can check to see if the attribute is set. use it, it's literally there for you 🫶

---

🌟 SUPPORT 🌟

Bugs may be submitted through <https://github.com/maxmind/GeoIP2-perl/issues>. found a bug? tell her, she'll fix it 💖

---

👑 AUTHORS 👑

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

the squad. the founding mothers and fathers of this module. we stan 🌈

---

⭐ 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. free as in freedom, free as in slay 💜

---

okay that's the whole page, you ate it, you understood it, you're basically a GeoIP2 expert now 🎀 this was GeoIP2...Reader(3pm), page generated by perl v5.36.0, dated 2022-11-21 — mwah, go query some databases bestie 💅✨