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.
<dependency>
<groupId>com.bigdatacloud</groupId>
<artifactId>bigdatacloud</artifactId>
<version>1.0.0</version>
</dependency>implementation 'com.bigdatacloud:bigdatacloud:1.0.0'Get a free API key at bigdatacloud.com/login. No credit card required.
export BIGDATACLOUD_API_KEY=your-key-hereimport 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);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"));| 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 |
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);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());
}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" NetworkEngineeringSampleMIT — see LICENSE.