Dave Rolsky > GeoIP2-0.0302 > GeoIP2::WebService::Client



Annotate this POD

View/Report Bugs
Module Version: 0.0302   Source   Latest Release: GeoIP2-0.040005


GeoIP2::WebService::Client - Perl API for the GeoIP2 web service end points


version 0.0302


  use 5.008;

  use GeoIP2::WebService::Client;

  my $client = GeoIP2::WebService::Client->new(
      user_id     => 42,
      license_key => 'abcdef123456',

  my $omni = $client->omni( ip => '' );

  my $country = $omni->country();
  say $country->iso_code();


This class provides a client API for all the GeoIP2 web service's end points. The end points are Country, City, City/ISP/Org, and Omni. Each end point returns a different set of data about an IP address, with Country returning the least data and Omni the most.

Each web service end point is represented by 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 web service does not return a particular piece of data for an IP address, the associated attribute is not populated.

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


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


The basic API for this class is the same for all of the web service end points. First you create a web service object with your MaxMind user_id and license_key, then you call the method corresponding to a specific end point, passing it the IP address you want to look up.

If the request succeeds, the method call will return a model class for the end point you called. This model in turn contains multiple record classes, each of which represents part of the data returned by the web service.

If the request fails, the client class throws an exception.


This class has a single constructor method:


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


All of the request methods accept a single argument:


This method calls the GeoIP2 Country end point. It returns a GeoIP2::Model::Country object.


This method calls the GeoIP2 Precision City end point. It returns a GeoIP2::Model::City object.


This method calls the GeoIP2 Precision City/ISP/Org end point. It returns a GeoIP2::Model::CityISPOrg object.


This method calls the GeoIP2 Precision Omni end point. It returns a GeoIP2::Model::Omni object.

User-Agent HEADER ^

This module will set 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.

This is set in order to help us support individual users, as well to determine support policies for dependencies and Perl itself.


For details on the possible errors returned by the web service itself, see http://dev.maxmind.com/geoip/geoip2/web-services for the GeoIP2 web service docs.

If the web service returns an explicit error document, this is thrown as a GeoIP2::Error::WebService exception object. If some other sort of error occurs, this is thrown as a GeoIP2::Error::HTTP object. The difference is that the web service error includes an error message and error code delivered by the web service. The latter is thrown when some sort of unanticipated error occurs, such as the web service returning a 500 or an invalid error document.

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

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. 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 end points return the same basic records, the attributes which can be populated vary between end points. In addition, while an end point 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 end point 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: