Dave Rolsky > GeoIP2-0.040000 > GeoIP2::Database::Reader



Annotate this POD

View/Report Bugs
Module Version: 0.040000   Source   Latest Release: GeoIP2-0.040002


GeoIP2::Database::Reader - Perl API for GeoIP2 databases


version 0.040000


  use 5.008;

  use GeoIP2::Database::Reader;

  my $reader = GeoIP2::Database::Reader->new(
      file      => '/path/to/database',
      languages => [ 'en', 'de', ]

  my $omni = $reader->omni( ip => '' );
  my $country = $omni->country();
  say $country->is_code();


This class provides a reader API for all GeoIP2 databases. The methods provided by this reader (country(), city(), city_isp_org() and omni()), correspond to the web service endpoints (Country, City, City/ISP/Org, and Omni). Each method returns a different set of data about an IP address, with country returning the least data and omni the most.

Each method returns 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 database does not return a particular piece of data for an IP address, the associated attribute is not populated.

The database may not return any information for an entire record, in which case all of the attributes for that record class will be empty.


The basic API for this class is the same for all database types. First you create a database reader object with your file and language params. 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. This model, in turn, contains multiple record classes, each of which represents part of the data returned by the database.

If the database cannot be read, the reader class throws an exception.


This class has a single constructor method:


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


All of the request methods accept a single argument:


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


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


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


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

Note that the data which makes the Omni web service different from City/ISP/Org is not available in any downloadable database. This means that calling the $reader->omni() always returns the same data as as $reader->city_isp_org().


In the case of a fatal error, the reader will throw a GeoIP2::Error::Generic 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.


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.

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.



Graham Knop <haarg@haarg.org>


This software is copyright (c) 2013 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.

syntax highlighting: