Node.js SDK · ipscope Docs

# Install

Install

npm install @ipscope/sdk-node

# Quickstart: single, batch & prefix lookups

Pass your API key explicitly or set IPSCOPE_KEY in your environment. Every lookup returns the canonical response schema with geo, network, connection, security and security_extensions.

Node.js

import { IpScopeClient } from '@ipscope/sdk-node';

const client = new IpScopeClient({
  apiKey: process.env.IPSCOPE_KEY,
  maxCacheEntries: 2048,
  cacheTtlMs: 60_000,
});

// 1. Single IPv4 or IPv6 lookup
const ipInfo = await client.lookupIp('198.51.100.7');
console.log(ipInfo.ip, ipInfo.geo.country_code, ipInfo.security.is_vpn);

// 2. Batch lookup (up to 100 IPs; reuses cached entries automatically)
const batch = await client.lookupBatch(['198.51.100.7', '1.1.1.1', '2606:4700:4700::1111']);
for (const item of batch.results) {
  console.log(item.ip, item.network.organization);
}

// 3. Memory-bounded streaming batch lookup for 10,000+ IPs
for await (const chunk of client.lookupBatchStream(largeIpList)) {
  for (const record of chunk.results) {
    // Constant O(chunk) memory overhead
  }
}

// 4. Network CIDR prefix lookup
const prefix = await client.lookupNetwork('198.51.100.0/24');
console.log(prefix.queried_cidr, prefix.record?.asn, prefix.record?.organization);

Responses

application/json

1. Single IPv4/IPv6 lookup response (GET /v1/ip/{ip})

{
  "ip": "198.51.100.7",
  "ip_version": 4,
  "matched_network": "198.51.100.0/24",
  "geo": {
    "country_code": "US",
    "declared_country_code": "US",
    "physical_country_code": "US",
    "is_virtual_location": false,
    "location_type": "physical",
    "confidence": 0.94,
    "subdivision": "Virginia",
    "city": "Ashburn",
    "postal_code": "20147",
    "latitude": 39.0438,
    "longitude": -77.4874,
    "accuracy_radius_km": 10,
    "timezone": "America/New_York"
  },
  "network": {
    "asn": 64501,
    "organization": "Example Cloud LLC"
  },
  "connection": {
    "connection_type": "hosting",
    "is_hosting": true,
    "is_residential": false,
    "is_mobile": false,
    "is_business": false
  },
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  },
  "security_extensions": {
    "abuse_velocity_score": 18,
    "is_known_scanner": false,
    "observation_recency_hours": 12,
    "anonymizer_reason": "vpn_handshake_confirmed",
    "threat_level": "medium",
    "abuse_velocity": "low",
    "confidence": 0.96
  },
  "dataset_version": "2026-10-27T00:00:00Z.crawl-1793088000000",
  "updated_at": "2026-10-27T00:00:00Z"
}

application/json

4. Network CIDR prefix lookup response (GET /v1/networks/{prefix}/{length})

{
  "queried_cidr": "198.51.100.0/24",
  "family": 4,
  "dataset_version": "2026-10-27T00:00:00Z.crawl-1793088000000",
  "record": {
    "prefix": "198.51.100.0/24",
    "family": 4,
    "asn": 64501,
    "organization": "Example Cloud LLC",
    "countryCode": "US",
    "city": "Ashburn",
    "locationType": "physical",
    "isVpn": true,
    "isHosting": true,
    "isTorExit": false,
    "isProxy": false,
    "anonymizerType": "vpn"
  }
}

# Architecture & runtime guarantees

Zero external runtime dependencies: built on native fetch and AbortSignal for Node.js 18+, Bun, Deno, and Cloudflare Workers.
Dual ESM and CommonJS exports with complete TypeScript interfaces (IpLookupResponse, BatchLookupResponse, NetworkPrefixLookupResponse).
Built-in AsyncGenerator (lookupBatchStream) that chunks arbitrary Iterable<string> or AsyncIterable<string> inputs into 100-IP batches.
Automatic 429 (Retry-After) and 5xx exponential backoff with full jitter.

# Reading local MMDB files

If you subscribe to a downloadable database, our .mmdb snapshots open directly in standard MaxMind DB readers with sub-microsecond in-memory lookups:

Node.js (MMDB)

import maxmind from 'maxmind';

const reader = await maxmind.open('/var/lib/ipscope/ipscope-complete.mmdb');
const record = reader.get('198.51.100.7');
console.log(record);

# Plain HTTP fallback

Need to call the REST API without installing a package? Use Node.js’s standard HTTP client directly:

Node.js (HTTP)

const res = await fetch('https://api.ipscope.io/v1/ip/198.51.100.7', {
  headers: { Authorization: `Bearer ${process.env.IPSCOPE_KEY}` },
});
if (!res.ok) throw new Error(`ipscope: ${res.status}`);
const info = await res.json();