Module com.maxmind.geoip2
Package com.maxmind.geoip2

Class WebServiceClient

java.lang.Object
com.maxmind.geoip2.WebServiceClient
All Implemented Interfaces:
GeoIp2Provider, WebServiceProvider, Closeable, AutoCloseable
public class WebServiceClient extends Object implements WebServiceProvider, Closeable

The WebServiceClient class provides a client API for all the GeoIP2 web services. The services are Country, City Plus, and Insights. Each service returns a different set of data about an IP address, with Country returning the least data and Insights the most.

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

The 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

To use the web service API, you must create a new WebServiceClient using the WebServiceClient.Builder. You must provide the Builder constructor your MaxMind accountId and licenseKey. To use the GeoLite2 web services instead of GeoIP2, set the host method on the builder to geolite.info. To use the Sandbox GeoIP2 web services instead of the production GeoIP2 web services, set the host method on the builder to sandbox.maxmind.com. You may also set a timeout or set the locales fallback order using the methods on the Builder. After you have created the WebServiceClient, you may then call the method corresponding to a specific service, passing it the IP address you want to look up.

If the request succeeds, the method call will return a model class for the service 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.

The WebServiceClient object is safe to share across threads. If you are making multiple requests, the object should be reused so that new connections are not created for each request.

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.