Official Node.js/TypeScript SDK for BigDataCloud APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, and Network Engineering.
Zero runtime dependencies — uses Node 18+ native fetch.
Looking for the browser/client-side package? Use
bigdatacloud-reverse-geocode-clientfor free reverse geocoding in the browser without an API key.
npm install bigdatacloudGet a free API key at bigdatacloud.com/login. No credit card required.
export BIGDATACLOUD_API_KEY=your-key-hereimport { BigDataCloudClient } from 'bigdatacloud';
// Reads BIGDATACLOUD_API_KEY from environment
const client = BigDataCloudClient.fromEnvironment();
// IP Geolocation
const geo = await client.ipGeolocation.get('1.1.1.1');
console.log(`${geo.location.city}, ${geo.country.name}`);
// Reverse Geocoding
const place = await client.reverseGeocoding.reverseGeocode(-33.87, 151.21);
console.log(`${place.city}, ${place.countryName}`);
// Phone Validation — countryCode is required
const phone = await client.verification.validatePhone('+61412345678', 'AU');
console.log(`Valid: ${phone.isValid}, Type: ${phone.lineType}`);
// Email Verification
const email = await client.verification.verifyEmail('user@example.com');
console.log(`Valid: ${email.isValid}, Disposable: ${email.isDisposable}`);The confidenceArea field may encode multiple polygons. Use the helper:
import { splitIntoPolygons } from 'bigdatacloud';
const geo = await client.ipGeolocation.getWithConfidenceArea('1.1.1.1');
const polygons = splitIntoPolygons(geo.confidenceArea);
polygons.forEach((ring, i) => console.log(`Ring ${i + 1}: ${ring.length} 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
const phone = await client.verification.validatePhone('+61412345678', 'AU');
// You know the end user's IP (pass their IP, not your server's)
const phone = await client.verification.validatePhoneByIp('0412345678', userIp);import { BigDataCloudError } from 'bigdatacloud';
try {
const geo = await client.ipGeolocation.get('1.1.1.1');
} catch (e) {
if (e instanceof BigDataCloudError) {
console.error(`API error ${e.statusCode}: ${e.message}`);
}
}export BIGDATACLOUD_API_KEY=your-key-here
npm run build
node samples/ipGeolocation.mjs
node samples/reverseGeocoding.mjs
node samples/verification.mjs
node samples/networkEngineering.mjsMIT — see LICENSE.