ipapi — Official Java client for ip-api.io

The official Java client for the ip-api.io IP intelligence platform. One client covers IP geolocation, email validation and verification (syntax, MX, SMTP deliverability), fraud detection and risk scoring, VPN/proxy/Tor detection, disposable email detection, ASN lookup, WHOIS, reverse DNS, MX records and domain age.

Built on java.net.http.HttpClient (Java 17+) with Jackson as the only dependency.

Install

<dependency>
    <groupId>io.ip-api</groupId>
    <artifactId>ipapi</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle: implementation("io.ip-api:ipapi:1.0.0")

Quickstart

import io.ipapi.IpApiClient;
import io.ipapi.model.IpInfo;
import io.ipapi.model.RiskScore;

IpApiClient client = IpApiClient.builder()
        .apiKey("YOUR_API_KEY") // free key at https://ip-api.io
        .build();

// Where is this IP, and is it risky?
IpInfo info = client.lookup("8.8.8.8");
System.out.println(info.location().country());        // "United States"
System.out.println(info.suspiciousFactors().isVpn()); // false

RiskScore risk = client.riskScore("8.8.8.8");
System.out.println(risk.score() + " " + risk.riskLevel()); // 0.0 low

An API key is required — the API rejects keyless requests with 401. Sign up at ip-api.io for a free key.

Documentation

Each guide documents the methods for one capability, with runnable examples and a link to the matching ip-api.io product page:

• IP geolocation & bulk lookup — lookup, lookupBatch
• Email validation & verification — emailInfo, validateEmail, validateEmailBatch
• Fraud detection & risk scoring — riskScore, emailRiskScore, ipReputation
• VPN, proxy & Tor detection — torCheck, suspiciousFactors
• ASN & DNS lookups — asn, whois, reverseDns, forwardDns, mxRecords
• Domain age checker — domainAge, domainAgeBatch
• Errors, rate limits & usage — exception types, rateLimit, usageSummary

Methods

Every method maps to one ip-api.io endpoint and its product page:

Method	Endpoint	Product page
lookup() / lookup(ip)	GET /api/v1/ip[/{ip}]	IP geolocation
lookupBatch(ips)	POST /api/v1/ip/batch (≤100 IPs)	Bulk IP lookup
emailInfo(email)	GET /api/v1/email/{email}	Email validation
validateEmail(email)	GET /api/v1/email/advanced/{email}	Advanced email validation
validateEmailBatch(emails)	POST /api/v1/email/advanced/batch (≤100)	Email list cleaning
riskScore() / riskScore(ip)	GET /api/v1/risk-score[/{ip}]	Risk score
emailRiskScore(email)	GET /api/v1/risk-score/email/{email}	Fraud detection
ipReputation(ip)	GET /api/v1/ip-reputation/{ip}	IP reputation
torCheck(ip)	GET /api/v1/tor/{ip}	Tor detection
asn(ip)	GET /api/v1/asn/{ip}	ASN lookup
whois(domain)	GET /api/v1/dns/whois/{domain}	WHOIS lookup
reverseDns(ip)	GET /api/v1/dns/reverse/{ip}	Reverse DNS
forwardDns(hostname)	GET /api/v1/dns/forward/{hostname}	—
mxRecords(domain)	GET /api/v1/dns/mx/{domain}	MX record lookup
domainAge(domain)	GET /api/v1/domain/age/{domain}	Domain age checker
domainAgeBatch(domains)	POST /api/v1/domain/age/batch	Domain age checker
rateLimit()	GET /api/v1/ratelimit	—
usageSummary()	GET /api/v1/usage/summary	—

All responses are typed records in io.ipapi.model. Nullable JSON fields map to reference types that may be null.

Error handling

The client throws typed unchecked exceptions and never retries — RateLimitException.getReset() tells you when your quota renews:

import io.ipapi.AuthenticationException;
import io.ipapi.RateLimitException;

try {
    client.lookup("8.8.8.8");
} catch (RateLimitException e) {
    System.out.printf("limit=%d remaining=%d resetsAt=%d%n",
            e.getLimit(), e.getRemaining(), e.getReset());
} catch (AuthenticationException e) {
    System.out.println("invalid API key");
}

See docs/error-handling.md for the full exception taxonomy.

Links

• Full tutorial: https://ip-api.io/docs/sdk/java
• Website: https://ip-api.io
• API reference: https://ip-api.io/api-docs.html
• OpenAPI spec: https://ip-api.io/openapi.json
• Get a free API key: https://ip-api.io

---

io.ip-api:ipapi is the official client for ip-api.io. It is not affiliated with ip-api.com or ipapi.com.