The
WebServiceClient 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.
Usage
To use the web service API, you must create a new
WebServiceClientusing the
WebServiceClient.Builder. You must provide the
Builder constructor your MaxMind
accountId and
licenseKey. You may also set a
timeout, specify a specific
host, 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 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.
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. Once you have finished making
requests, you should close the object to ensure the connections are closed
and any resources are promptly returned to the system.
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.