com.maxmind.geoip2

Class WebServiceClient

java.lang.Object

com.maxmind.geoip2.WebServiceClient

All Implemented Interfaces:

GeoIp2Provider

public class WebServiceClient
extends Object
implements GeoIp2Provider

This class provides a client API for all the GeoIP2 Precision web service end points. The end points are Country 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.

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 userId and licenseKey, 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.

Exceptions

For details on the possible errors returned by the web service itself, see the GeoIP2 web service documentation.

If the web service returns an explicit error document, this is thrown as a InvalidRequestException. If some other sort of transport error occurs, this is thrown as a HttpException. 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 HttpException.

Finally, if the web service returns a 200 but the body is invalid, the client throws a GeoIp2Exception.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WebServiceClient.Builder Builder creates instances of WebServiceClient from values set by the methods.

Method Summary

Modifier and Type	Method and Description
CityResponse	city()
CityResponse	city(InetAddress ipAddress)
CountryResponse	country()
CountryResponse	country(InetAddress ipAddress)
InsightsResponse	insights()
InsightsResponse	insights(InetAddress ipAddress)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

country

public CountryResponse country()
                        throws IOException,
                               GeoIp2Exception

Returns:

A Country model for the requesting IP address

Throws:

GeoIp2Exception - if there is an error from the web service

IOException - if an IO error happens during the request

country

public CountryResponse country(InetAddress ipAddress)
                        throws IOException,
                               GeoIp2Exception

Specified by:

country in interface GeoIp2Provider

Parameters:

ipAddress - IPv4 or IPv6 address to lookup.

Returns:

A Country model for the requested IP address.

Throws:

IOException - if there is an IO error

GeoIp2Exception - if there is an error looking up the IP

city

public CityResponse city()
                  throws IOException,
                         GeoIp2Exception

Returns:

A City model for the requesting IP address

Throws:

GeoIp2Exception - if there is an error from the web service

IOException - if an IO error happens during the request

city

public CityResponse city(InetAddress ipAddress)
                  throws IOException,
                         GeoIp2Exception

Specified by:

city in interface GeoIp2Provider

Parameters:

ipAddress - IPv4 or IPv6 address to lookup.

Returns:

A City model for the requested IP address.

Throws:

IOException - if there is an IO error

GeoIp2Exception - if there is an error looking up the IP

insights

public InsightsResponse insights()
                          throws IOException,
                                 GeoIp2Exception

Returns:

An Insights model for the requesting IP address

Throws:

GeoIp2Exception - if there is an error from the web service

IOException - if an IO error happens during the request

insights

public InsightsResponse insights(InetAddress ipAddress)
                          throws IOException,
                                 GeoIp2Exception

Parameters:

ipAddress - IPv4 or IPv6 address to lookup.

Returns:

A Insight model for the requested IP address.

Throws:

GeoIp2Exception - if there is an error looking up the IP

IOException - if there is an IO error