Skip to content

README.md

Latest commit

 

History

History
111 lines (78 loc) · 3.58 KB

README.md

File metadata and controls

111 lines (78 loc) · 3.58 KB

BigDataCloud Node.js SDK

npm License: MIT

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-client for free reverse geocoding in the browser without an API key.

Installation

npm install bigdatacloud

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 { 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}`);

Confidence Area

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`));

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
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);

Error Handling

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}`);
  }
}

Samples

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.mjs

License

MIT — see LICENSE.