BigDataCloud Java SDK

Official Java SDK for BigDataCloud APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, and Network Engineering.

Requires Java 11+. Uses Java's built-in HttpClient — no extra HTTP library needed.

Installation

Maven

<dependency>
    <groupId>com.bigdatacloud</groupId>
    <artifactId>bigdatacloud</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'com.bigdatacloud:bigdatacloud:1.0.0'

API Key

Get a free API key at bigdatacloud.com/login. No credit card required.

export BIGDATACLOUD_API_KEY=your-key-here

Quick Start

import com.bigdatacloud.BigDataCloudClient;
import com.bigdatacloud.models.*;

// Reads BIGDATACLOUD_API_KEY from environment
BigDataCloudClient client = BigDataCloudClient.fromEnvironment();

// Or pass the key directly
// BigDataCloudClient client = new BigDataCloudClient("your-key-here");

// IP Geolocation
IpGeolocationResponse geo = client.ipGeolocation().get("1.1.1.1", "en");
System.out.println(geo.location.city + ", " + geo.country.name);

// Reverse Geocoding
ReverseGeocodeResponse place = client.reverseGeocoding().reverseGeocode(-33.87, 151.21, "en");
System.out.println(place.city + ", " + place.countryName);

// Phone Validation — countryCode is required
PhoneValidationResponse phone = client.verification().validatePhone("+61412345678", "AU");
System.out.println("Valid: " + phone.isValid + ", Type: " + phone.lineType);

// Email Verification
EmailVerificationResponse email = client.verification().verifyEmail("user@example.com");
System.out.println("Valid: " + email.isValid + ", Disposable: " + email.isDisposable);

Confidence Area

The confidenceArea field may encode multiple polygons. Use the helper:

import com.bigdatacloud.ConfidenceAreaHelper;
import com.bigdatacloud.models.GeoPoint;
import java.util.List;

IpGeolocationWithConfidenceAreaResponse geo =
    client.ipGeolocation().getWithConfidenceArea("1.1.1.1", "en");

List<List<GeoPoint>> polygons =
    ConfidenceAreaHelper.splitIntoPolygons(geo.confidenceArea);
polygons.forEach(ring ->
    System.out.println("Ring: " + ring.size() + " points"));

Available APIs

Client	Methods
client.ipGeolocation()	get, getWithConfidenceArea, getFull, getCountryByIp, getCountryInfo, getAllCountries, getHazardReport, getUserRisk, getAsnInfo, getNetworkByIp, getTimezoneByIanaId, getTimezoneByIp, parseUserAgent
client.reverseGeocoding()	reverseGeocode, reverseGeocodeWithTimezone, getTimezoneByLocation
client.verification()	validatePhone, validatePhoneByIp, verifyEmail
client.networkEngineering()	getAsnInfoFull, getReceivingFrom, getTransitTo, getBgpPrefixes, getNetworksByCidr, getAsnRankList, getTorExitNodes

Phone Validation

Both methods require explicit country context — never uses server IP silently:

// You know the country
PhoneValidationResponse phone = client.verification().validatePhone("+61412345678", "AU");

// You know the end user's IP (pass their IP, not your server's)
PhoneValidationResponse phone = client.verification().validatePhoneByIp("0412345678", userIp);

Error Handling

import com.bigdatacloud.BigDataCloudException;

try {
    IpGeolocationResponse geo = client.ipGeolocation().get("1.1.1.1", "en");
} catch (BigDataCloudException e) {
    System.out.println("API error " + e.getStatusCode() + ": " + e.getMessage());
}

Samples

export BIGDATACLOUD_API_KEY=your-key-here
mvn package dependency:copy-dependencies -q
javac -cp "target/bigdatacloud-1.0.0.jar:target/dependency/*" -d samples/out samples/*.java
java -cp "target/bigdatacloud-1.0.0.jar:target/dependency/*:samples/out" IpGeolocationSample
java -cp "target/bigdatacloud-1.0.0.jar:target/dependency/*:samples/out" ReverseGeocodingSample
java -cp "target/bigdatacloud-1.0.0.jar:target/dependency/*:samples/out" VerificationSample
java -cp "target/bigdatacloud-1.0.0.jar:target/dependency/*:samples/out" NetworkEngineeringSample

License

MIT — see LICENSE.