Java IP Address Database Reader Documentation

The IPQS Java reader brings a new standard of performance and compression to our IP reputation and geo location services. Setting up the reader can be achieved in minutes and provides access to our proxy detection database.

Installation

You can currently download a release copy of our source code from our github. Alternatively you can use our maven repository to do the install automatically (to update to the latest version simply change the version and skip to step 3):

Step #1: Simply add a dependency for our reader to your pom.xml file like such (remove ... and add parent tag only if none exists):

    <dependencies>
        ...
        <dependency>
            <groupId>com.ipqualityscore</groupId>
            <artifactId>ipqualityscore-java-db-reader</artifactId>
            <version>1.0.7</version>
        </dependency>
        ...
    </dependencies>

Step #2: Next add our repository to your pom.xml file like such (remove ... and add parent tag only if none exists):

    <repositories>
        ...
        <repository>
            <id>ipqualityscore</id>
            <name>IPQualityScore Java Flat File DB Reader</name>
            <url>https://downloads.ipqualityscore.com/maven2</url>
        </repository>
        ...
    </repositories>

Step #3: Finally update your dependencies on the command line (or via your IDE):

    mvn dependency:resolve

Usage

Using our flat file database system to lookup an IP address is simple:

import com.ipqualityscore.JavaIPQSDBReader.*;

...

try {
    // Open a DB file reader.
    FileReader reader = DBReader.Open("IPQualityScore-IP-Reputation-Database-Sample.ipqs");
    
    // Request data about a given IP address.
    String ip = "8.8.0.0";
    IPQSRecord record = reader.Fetch(ip);

    // Use the IPQSRecord to print some data about this IP.
    if(record.isProxy()){
        System.out.println(ip + " is a proxy.");
    } else {
        System.out.println(ip + " is not a proxy.");
    }
} catch (Exception e){
    System.out.println(e.getMessage());
}

IPQSRecord Methods

Depending on which database file you receive some of these methods may be unavailable. If the method in question is unavailable in your database the method return will default to Java's default value for that type or false.

Method

Type

Description

record.isProxy()

bool

Is this IP address suspected to be a proxy? (SOCKS, Elite, Anonymous, VPN, Tor, etc.)

record.isVPN()

bool

Is this IP suspected of being a VPN connection? This can include data center ranges which can become active VPNs at any time. The "proxy" status will always be true when this value is true.

record.isTOR()

bool

Is this IP suspected of being a TOR connection? This can include previously active TOR nodes and exits which can become active TOR exits at any time. The "proxy" status will always be true when this value is true.

record.isCrawler()

bool

Is this IP associated with being a confirmed crawler from a mainstream search engine such as Googlebot, Bingbot, Yandex, etc. based on hostname or IP address verification.

record.isBot()

bool

Indicates if bots or non-human traffic has recently used this IP address to engage in automated fraudulent behavior. Provides stronger confidence that the IP address is suspicious.

record.hasRecentAbuse()

bool

This value will indicate if there has been any recently verified abuse across our network for this IP address. Abuse could be a confirmed chargeback, compromised device, fake app install, or similar malicious behavior within the past few days.

record.isBlacklisted()

bool

This value will indicate if the IP has been blacklisted by any 3rd party agency for spam, abuse or fraud.

record.isPrivate()

bool

This value will indicate if the IP is a private, non-routable IP address.

record.isMobile()

bool

This value will indicate if the IP is likely owned by a mobile carrier.

record.hasOpenPorts()

bool

This value will indicate if the IP has recently had open (listening) ports.

record.isHostingProvider()

bool

This value will indicate if the IP is likely owned by a hosting provider or is leased to a hosting company.

record.isActiveVPN()

bool

Identifies active VPN connections used by popular VPN services and private VPN servers.

record.isActiveTOR()

bool

Identifies active TOR exits on the TOR network.

record.isPublicAccessPoint()

bool

Indicates if this IP is likely to be a public access point such as a coffee shop, college or library.

record.getConnectionType().getRaw()

int

A numerical representation for the suspected type of connection for this IP address. It is generally recommended you call the toString() function listed below instead of using this value, but it is available as an option.

#	Enum Description
1	Residential IP
2	Mobile IP
3	Corporate IP
4	Data Center IP
5	Educational IP

record.getConnectionType.toString()

int

A string representation for the suspected type of connection for this IP address. (Residential, Mobile, Corporate, Data Center, Education or Unknown)

record.getAbuseVelocity().getRaw()

int

How frequently the IP address is engaging in abuse across the IPQS threat network. Can be used in combination with the Fraud Score to identify bad behavior. It is generally recommended you call the toString() function listed below instead of using this value, but it is available as an option.

#	Enum Description
0	No Recent Abuse
1	Low Recent Abuse IP
2	Medium Recent Abuse IP
3	High Recent Abuse IP

record.getAbuseVelocity().toString()

int

How frequently the IP address is engaging in abuse across the IPQS threat network. Values can be "high", "medium", "low", or "none".

record.getCountry()

string

Two character country code of IP address or "N/A" if unknown.

record.getCountryName()

string

A full text representation of the country name. NOTE: Calling this function requires network access or a valid countrylist.raw updated within the last week. See the country list API for details.

record.getCity()

string

City of IP address if available or "N/A" if unknown.

record.getISP()

string

ISP if one is known. Otherwise "N/A".

record.getOrganization()

string

Organization if one is known. Can be parent company or sub company of the listed ISP. Otherwise "N/A".

record.getASN()

int

Autonomous System Number if one is known. Zero if nonexistent.

record.getTimezone()

string

Timezone of IP address if available or "N/A" if unknown.

record.getLatitude()

float32

Latitude of IP address if available or 0.00 if unknown.

record.getLongitude()

float32

Longitude of IP address if available or 0.00 if unknown.

record.getFraudScore().forStrictness(int)

int

Returns a fraud score for this IP address based on a strictness level. This method requires an int for the "strictness level" of the query and can be 0, 1 or 2. Some databases may contain 1 entry, others all 3. It is recommended that you use the lowest strictness for Fraud Scoring. Increasing this value will expand the tests we perform. Levels 2+ have a higher risk of false-positives.

Usage Notes

Each database only holds either IPv4 or IPv6 data. Therefore you may need two instances of the reader available depending on your use case.