IPLocate Geolocation Client for Java

A Java client for the IPLocate.io geolocation API. Look up detailed geolocation and threat intelligence data for any IP address:

• IP geolocation: IP to country, IP to city, IP to region/state, coordinates, timezone, postal code
• ASN information: Internet service provider, network details, routing information
• Privacy & threat detection: VPN, proxy, Tor, hosting provider detection
• Company information: Business details associated with IP addresses - company name, domain, type (ISP/hosting/education/government/business)
• Abuse contact: Network abuse reporting information
• Hosting detection: Cloud provider and hosting service detection using our proprietary hosting detection engine

See what information we can provide for your IP address.

Getting started

You can make 1,000 free requests per day with a free account. For higher plans, check out API pricing.

Installation

Maven: Add this dependency to your pom.xml:

<dependency>
<groupId>io.iplocate</groupId>
<artifactId>java-iplocate</artifactId>
<version>1.0.0</version>
</dependency>

Gradle: Add this to your build.gradle file:

implementation 'io.iplocate:java-iplocate:1.0.0'

Quick start

packagecom.example; // Your package nameimportio.iplocate.client.IPLocateClient;
importio.iplocate.client.exceptions.IPLocateException;
importio.iplocate.client.model.IPLocateResponse;
importio.iplocate.client.model.PrivacyDetails;
publicclassIPLocateExample {
publicstaticvoidmain(String[] args) {
// Create a new client with your API key// Get your free API key from https://iplocate.io/signupIPLocateClientclient = newIPLocateClient("your-api-key");
try {
// Look up an IP addressIPLocateResponseresult = client.lookup("8.8.8.8");
System.out.println("IP: " + result.getIp());
if (result.getCountry() != null) {
System.out.println("Country: " + result.getCountry());
}
if (result.getCity() != null) {
System.out.println("City: " + result.getCity());
}
// Check privacy flagsPrivacyDetailsprivacy = result.getPrivacy();
if (privacy != null) {
System.out.println("Is VPN: " + privacy.isVpn());
System.out.println("Is Proxy: " + privacy.isProxy());
}
} catch (IPLocateExceptione) {
System.err.println("IPLocate API Error: " + e.getMessage());
// For more detailed error handling, catch specific exceptions// e.g., IPLocateApiKeyException, IPLocateInvalidIPException, etc.e.printStackTrace();
}
}
}

Get the country for an IP address

if (result.getCountry() != null && result.getCountryCode() != null) {
System.out.printf("Country: %s (%s)\n", result.getCountry(), result.getCountryCode());
}

Get the currency code for a country by IP address

if (result.getCurrencyCode() != null) {
System.out.printf("Currency: %s\n", result.getCurrencyCode());
}

Get the calling code for a country by IP address

if (result.getCallingCode() != null) {
System.out.printf("Calling code: %s\n", result.getCallingCode());
}

Authentication

Get your free API key from IPLocate.io, and pass it to the IPLocateClient constructor:

IPLocateClientclient = newIPLocateClient("your-api-key");

Examples

IP address geolocation lookup

IPLocateClientclient = newIPLocateClient("your-api-key");
try {
IPLocateResponseresult = client.lookup("203.0.113.1");
if (result.getCountry() != null && result.getCountryCode() != null) {
System.out.printf("Country: %s (%s)\n", result.getCountry(), result.getCountryCode());
}
if (result.getLatitude() != null && result.getLongitude() != null) {
System.out.printf("Coordinates: %.4f, %.4f\n", result.getLatitude(), result.getLongitude());
}
} catch (IPLocateExceptione) {
System.err.println("Error looking up IP: " + e.getMessage());
}

Get your own IP address information

This will look up the IP address as seen by the IPLocate.io API server.

IPLocateClientclient = newIPLocateClient("your-api-key");
try {
IPLocateResponseresult = client.lookupCurrentIp();
System.out.println("Your IP: " + result.getIp());
// Access other fields as needed
} catch (IPLocateExceptione) {
System.err.println("Error looking up current IP: " + e.getMessage());
}

Check for VPN/Proxy Detection

IPLocateClientclient = newIPLocateClient("your-api-key");
try {
IPLocateResponseresult = client.lookup("192.0.2.1"); // Example IPPrivacyDetailsprivacy = result.getPrivacy();
if (privacy != null) {
if (privacy.isVpn()) {
System.out.println("This IP is using a VPN");
}
if (privacy.isProxy()) {
System.out.println("This IP is using a proxy");
}
if (privacy.isTor()) {
System.out.println("This IP is using Tor");
}
}
} catch (IPLocateExceptione) {
System.err.println("Error during privacy check: " + e.getMessage());
}

AsnDetails and network information

IPLocateClientclient = newIPLocateClient("your-api-key");
try {
IPLocateResponseresult = client.lookup("8.8.8.8");
io.iplocate.client.model.AsnDetailsasnInfo = result.getAsn();
if (asnInfo != null) {
System.out.println("ASN: " + asnInfo.getAsn());
System.out.println("ISP: " + asnInfo.getName());
System.out.println("Network: " + asnInfo.getRoute());
}
} catch (IPLocateExceptione) {
System.err.println("Error fetching ASN info: " + e.getMessage());
}

Response structure

The io.iplocate.client.model.IPLocateResponse class contains all available data. The fields are similar to the JSON structure returned by the API.

publicclassIPLocateResponse {
publicclassIPLocateResponse {
privateStringip;
privateStringcountry;
@JsonProperty("country_code")
privateStringcountryCode;
@JsonProperty("is_eu")
privateBooleaneu;
privateStringcity;
privateStringcontinent;
privateDoublelatitude;
privateDoublelongitude;
@JsonProperty("time_zone")
privateStringtimeZone;
@JsonProperty("postal_code")
privateStringpostalCode;
privateStringsubdivision;
@JsonProperty("currency_code")
privateStringcurrencyCode;
@JsonProperty("calling_code")
privateStringcallingCode;
privateStringnetwork;
privateAsnDetailsasn;
privatePrivacyDetailsprivacy;
privateCompanyDetailscompany;
privateHostingDetailshosting;
privateAbuseDetailsabuse;
// Plus, getter methods for all fields, e.g., getIp(), getCountry(), etc.
}

Note: Fields representing objects (like asn, privacy) or optional scalar values (like country, city) may be null if data is not available for a given IP. Always check for null before accessing their properties or methods. Boolean fields like isEu will have default values (e.g., false) if not explicitly set.

Error handling

The client throws specific exceptions that extend IPLocateException for different error scenarios.

Common API errors and their corresponding Java exceptions:

• 400 Bad Request (Invalid IP address format): IPLocateInvalidIPException
• 403 Forbidden (Invalid API key): IPLocateApiKeyException
• 404 Not Found (IP address not found): IPLocateNotFoundException
• 429 Too Many Requests (Rate limit exceeded): IPLocateRateLimitException
• 5xx Server Error: IPLocateServiceException
• Other API errors: IPLocateApiException

All these exceptions extend IPLocateException.

API reference

For complete API documentation, visit iplocate.io/docs.

License

This project is licensed under the MIT License - see the LICENSE file for details

Testing

To run tests for this Java library:

Maven:

mvn test

Gradle:

gradle test

About IPLocate.io

Since 2017, IPLocate has set out to provide the most reliable and accurate IP address data.

We process 50TB+ of data to produce our comprehensive IP geolocation, IP to company, proxy and VPN detection, hosting detection, ASN, and WHOIS data sets. Our API handles over 15 billion requests a month for thousands of businesses and developers.

• Email: support@iplocate.io
• Website: iplocate.io
• Documentation: iplocate.io/docs
• Sign up for a free API Key: iplocate.io/signup