@trellisdigitalservices/ip-atlas

Official Node.js / TypeScript client for the IP-Atlas API — IP geolocation, ASN lookup, VPN/proxy/datacenter detection, batch lookup, and account management.

Install

npm install @trellisdigitalservices/ip-atlas

Requires Node.js 18+. No runtime dependencies — uses the built-in fetch API.

Quickstart

Without an API key (free anonymous tier)

import { IPAtlas } from '@trellisdigitalservices/ip-atlas';

const client = new IPAtlas();

// Look up your own IP
const self = await client.lookupSelf();
console.log(self.country, self.org);

// Look up a specific IP (anonymous is limited to 60 req/min)
const result = await client.lookup('8.8.8.8');
console.log(result.asn, result.is_datacenter);

With an API key

import { IPAtlas } from '@trellisdigitalservices/ip-atlas';

const client = new IPAtlas({ apiKey: 'ipa_live_...' });

const result = await client.lookup('1.1.1.1');
console.log(result.country, result.city, result.org);

Batch lookup (up to 100 IPs)

import { IPAtlas } from '@trellisdigitalservices/ip-atlas';

const client = new IPAtlas({ apiKey: 'ipa_live_...' });

const batch = await client.lookupBatch(['8.8.8.8', '1.1.1.1', 'not-an-ip']);
for (const item of batch.results) {
  if ('error' in item) {
    console.error(`${item.ip}: ${item.error}`);
  } else {
    console.log(item.ip, item.country, item.org);
  }
}

Responses come back in the same order as the input list. Each element is either an IPResult (success) or a { ip, error } object for per-IP errors. Request-level failures (auth, quota) surface as thrown IPAtlasError instances.

Account management

const info = await client.account();
console.log(`Plan: ${info.plan}, used ${info.monthly_used}/${info.monthly_limit} this month`);

// Rotate the key (old one is revoked, new one returned once)
const { api_key } = await client.rotateKey();

Error handling

import { IPAtlas, IPAtlasError } from '@trellisdigitalservices/ip-atlas';

const client = new IPAtlas({ apiKey: 'ipa_live_...' });

try {
  const result = await client.lookup('not-an-ip');
} catch (err) {
  if (err instanceof IPAtlasError) {
    console.error(`API error ${err.status}:`, err.body);
  }
}

API

new IPAtlas(opts?)

| Option | Type | Default | Description | |-----------|----------|------------------------------|-------------------------------------| | apiKey | string | — | API key sent as X-API-Key header | | baseUrl | string | https://api.ip-atlas.io | Override the API base URL |

client.lookup(ip): Promise<IPResult>

Returns geolocation + ASN + threat data for the given IPv4 or IPv6 address.

client.lookupSelf(): Promise<IPResult>

Returns data for the caller's own IP address.

client.lookupBatch(ips): Promise<BatchResult>

Looks up up to 100 IPs in a single request. Returns { results: Array<IPResult | { ip, error }> } in the same order as the input list.

client.account(): Promise<AccountInfo>

Returns the plan, key prefix, daily/monthly usage, and Stripe linkage for the bound API key.

client.rotateKey(): Promise<{ api_key, key_prefix }>

Revokes the current key and issues a replacement with the same plan. The new plaintext key is only returned once.

Links

• Documentation
• Get an API key
• GitHub