Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GeoIP2::WebService::ClUser(Contributed Perl DocumGeoIP2::WebService::Client(3)

NAME
       GeoIP2::WebService::Client - Perl API for the GeoIP2 Precision web
       services

VERSION
       version 2.003005

SYNOPSIS
	 use 5.008;

	 use GeoIP2::WebService::Client;

	 # This	creates	a Client object	that can be reused across requests.
	 # Replace "42"	with your user id and "abcdef123456" with your license
	 # key.
	 my $client = GeoIP2::WebService::Client->new(
	     user_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";

DESCRIPTION
       This class provides a client API	for all	the GeoIP2 Precision web
       service end points. The end points are Country, City, and Insights.
       Each end	point returns a	different set of data about an IP address,
       with Country returning the least	data and Insights 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.

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

USAGE
       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.

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

CONSTRUCTOR
       This class has a	single constructor method:

   GeoIP2::WebService::Client->new()
       This method creates a new client	object.	It accepts the following
       arguments:

       o   user_id

	   Your	MaxMind	User ID. Go to
	   <https://www.maxmind.com/en/my_license_key> to see your MaxMind
	   User	ID and license key.

	   This	argument is required.

       o   license_key

	   Your	MaxMind	license	key. Go	to
	   <https://www.maxmind.com/en/my_license_key> to see your MaxMind
	   User	ID and license key.

	   This	argument is required.

       o   locales

	   This	is an array reference where each value is a string indicating
	   a locale.  This argument will be passed onto	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.

	   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.

	   Currently, the valid	list of	locale codes is:

	   o	   de -	German

	   o	   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.

	   o	   es -	Spanish

	   o	   fr -	French

	   o	   ja -	Japanese

	   o	   pt-BR - Brazilian Portuguese

	   o	   ru -	Russian

	   o	   zh-CN - simplified Chinese

	   Passing any other locale code will result in	an error.

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

       o   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.

       o   ua

	   This	argument allows	you to your own	LWP::UserAgent object. This is
	   useful if you cannot	use a vanilla LWP object, for example if you
	   need	to set proxy parameters.

	   This	can actually be	any object which supports "agent()" and
	   "request()" methods.	This method will be called with	an
	   HTTP::Request object	as its only argument. This method must return
	   an HTTP::Response object.

REQUEST	METHODS
       All of the request methods accept a single argument:

       o   ip

	   This	must be	a valid	IPv4 or	IPv6 address, or the string "me". This
	   is the address that you want	to look	up using the GeoIP2 web
	   service.

	   If you pass the string "me" then the	web service returns data on
	   the client system's IP address. Note	that this is the IP address
	   that	the web	service	sees. If you are using a proxy,	the web
	   service will	not see	the client system's actual IP address.

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

EXCEPTIONS
       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.

WHAT DATA IS RETURNED?
       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.

SUPPORT
       Bugs may	be submitted through
       <https://github.com/maxmind/GeoIP2-perl/issues>.

AUTHORS
       o   Dave	Rolsky <drolsky@maxmind.com>

       o   Greg	Oschwald <goschwald@maxmind.com>

       o   Mark	Fowler <mfowler@maxmind.com>

       o   Olaf	Alders <oalders@maxmind.com>

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

perl v5.24.1			  2017-05-08	 GeoIP2::WebService::Client(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SSL | USAGE | IP GEOLOCATION USAGE | CONSTRUCTOR | REQUEST METHODS | User-Agent HEADER | EXCEPTIONS | WHAT DATA IS RETURNED? | SUPPORT | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=GeoIP2::WebService::Client&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help