Skip to content
Official Java Client for Ipregistry, a Fast, Reliable IP Geolocation and Threat Data API.
Java
Branch: master
Clone or download
Latest commit c3c09f8 Aug 9, 2019

README.md

Ipregistry

Ipregistry Java Client Library

License Travis Maven Central Javadocs

This is the official Java client library for the Ipregistry IP geolocation and threat data API, allowing you to lookup your own IP address or specified ones. Responses include more than 50 data points including location, currency, timezone, threat information, but also carrier, company data and more.

Getting Started

You'll need an Ipregistry API key, which you can get along with 100,000 free lookups by signing up for a free account at https://ipregistry.co.

Installation

Maven

<dependency>
    <groupId>co.ipregistry</groupId>
    <artifactId>ipregistry-client</artifactId>
    <version>2.1.1</version>
</dependency>

Gradle

implementation 'co.ipregistry:ipregistry-client:2.1.1'

Quick start

Single IP Lookup

import co.ipregistry.api.client.exceptions.ApiException;
import co.ipregistry.api.client.exceptions.ClientException;
import co.ipregistry.api.client.model.IpInfo;

public class SingleIpLookup {

    public static void main(String[] args) {
        IpregistryClient client = new IpregistryClient("tryout");

        try {
            // Lookup IP data for the current node and network interface used to execute this code
            RequesterIpInfo requesterIpInfo = client.lookup();
            System.out.println(requesterIpInfo.getLocation().getCountry().getName());
            System.out.println(requesterIpInfo);

            // Here is another example to lookup data for a given IP address
            // You may already have it or you can get the client IP from a request header
            IpInfo ipInfo = client.lookup("54.85.132.205");
            System.out.println(ipInfo);
        } catch (ApiException e) {
            // Handle API errors (e.g. insufficient credits, throttling) here
            e.printStackTrace();
        } catch (ClientException e) {
            // Handle client errors (e.g. network error) here
            e.printStackTrace();
        }
    }
    
}

Batch IP Lookup

import co.ipregistry.api.client.ipregistrygistry;
import co.ipregistry.api.client.exceptions.ApiException;
import co.ipregistry.api.client.exceptions.ClientException;
import co.ipregistry.api.client.exceptions.IpInfoException;
import co.ipregistry.api.client.model.IpInfo;
import co.ipregistry.api.client.model.IpInfoList;

import java.util.Arrays;

public class BatchIpLookup {

    public static void main(String[] args) {
        IpregistryClient client = new IpregistryClient("tryout");

        try {
            IpInfoList ipInfoList =
                    client.lookup(Arrays.asList("73.2.2.2", "8.8.8.8", "2001:67c:2e8:22::c100:68b"));

            for (int i = 0; i < ipInfoList.size(); i++) {
                try {
                    IpInfo ipInfo = ipInfoList.get(i);
                    // Here is an example to print out the country name associated with each IP address
                    System.out.println(ipInfo.getLocation().getCountry().getName());
                } catch (IpInfoException e) {
                    // Handle batch lookup error (e.g. invalid IP address) here
                    e.printStackTrace();
                }
            }
        } catch (ApiException e) {
            // Handle API errors (e.g. insufficient credits, throttling) here
            e.printStackTrace();
        } catch(ClientException e) {
            // Handle client errors (e.g. network error) here
            e.printStackTrace();
        }
    }

}

Caching

The Ipregistry client library has built-in support for in-memory caching.

To enable the default caching strategy, pass an instance of DefaultCache to the Ipregistry client:

IpregistryConfig config =
        IpregistryConfig.builder()
                .apiKey("YOUR_API_KEY").build();

IpregistryClient ipregistry = new IpregistryClient(config, DefaultCache.builder().build());

By default, the last 8096 successful lookup results are stored in-memory for 24h.

The DefaultCache implementation supports multiple eviction policies (i.e. size based, time based, memory consumption based):

DefaultCache cache =
        DefaultCache.builder()
                .concurrencyLevel(16)
                .expireAfter(3600000)
                .initialCapacity(512)
                .maximumSize(4096)
                .referenceType(ValuesReferenceType.WEAK)
                .build();

You can also provide your own cache implementation by implementing the IpregistryCache interface.

To disable caching, you can use the NoCache class.

Errors

All Ipregistry exceptions inherit the IpregistryException class.

Main subtypes are ApiException and ClientException.

Exceptions of type ApiException include a code field that maps to the one described in the Ipregistry documentation.

Filtering bots

You might want to prevent Ipregistry API calls for crawlers or bots browsing your pages.

A manner to proceed is to identify bots from the user agent. To ease this process, the library includes a utility method:

import co.ipregistry.api.client.ipregistrygistry;
import co.ipregistry.api.client.exceptions.ApiException;
import co.ipregistry.api.client.exceptions.ClientException;
import co.ipregistry.api.client.model.IpInfo;
import co.ipregistry.api.client.util.UserAgent;

public class SingleIpLookupFilteringBots {

    public static void main(String[] args) {
        IpregistryClient client = new IpregistryClient("tryout");

        // For testing purposes, you can retrieve you current user agent from:
        // https://api.ipregistry.co/user_agent?key=tryout (look at the field named "header")
        if (UserAgent.isBot("TO_REPLACE_BY_USER_AGENT_RETRIEVED_FROM_REQUEST_HEADER")) {
            try {
                IpData ipInfo = client.lookup("8.8.8.8");
                // Here is an example to print out the country name associated with the IP address
                System.out.println(ipInfo.getLocation().getCountry().getName());
            } catch (ApiException e) {
                // Handle API errors (e.g. insufficient credits, throttling) here
                e.printStackTrace();
            } catch (ClientException e) {
                // Handle client errors (e.g. network error) here
                e.printStackTrace();
            }
        }
    }

}

Other Libraries

There are official Ipregistry client libraries available for many languages including Javascript, Python, Typescript and more.

Are you looking for an official client with a programming language or framework we do not support yet? let us know.

You can’t perform that action at this time.