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("[email protected]"); 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" NetworkEngineeringSample
MIT — see LICENSE.