ip-api-io — Official JavaScript/TypeScript client for ip-api.io

The official JavaScript/TypeScript client for the ip-api.io IP intelligence platform. One typed, zero-dependency client covers IP geolocation, email validation and verification (syntax, MX, SMTP deliverability), fraud detection and risk scoring, VPN/proxy/Tor detection, disposable email detection, ASN lookup, WHOIS, reverse DNS, MX records and domain age.

Built on the global fetch (Node ≥18, Deno, Bun and browsers) — zero dependencies, fully typed, ESM + CJS.

Install

npm install ip-api-io

Quickstart

import { IpApiClient } from "ip-api-io";

const client = new IpApiClient({ apiKey: "YOUR_API_KEY" }); // free key at https://ip-api.io

// Where is this IP, and is it risky?
const info = await client.lookup("8.8.8.8");
console.log(info.location.country);            // "United States"
console.log(info.suspicious_factors.is_vpn);   // false

const risk = await client.riskScore("8.8.8.8");
console.log(risk.score, risk.risk_level);      // 0 "low"

const email = await client.validateEmail("[email protected]");
console.log(email.reachable, email.disposable); // "yes" false

An API key is required — the API rejects keyless requests with 401. Sign up at ip-api.io for a free key.

Documentation

Each guide below documents the methods for one capability, with runnable examples and a link to the matching ip-api.io product page:

• IP geolocation & bulk lookup — lookup, lookupBatch
• Email validation & verification — emailInfo, validateEmail, validateEmailBatch
• Fraud detection & risk scoring — riskScore, emailRiskScore, ipReputation
• VPN, proxy & Tor detection — torCheck, suspicious_factors
• ASN & DNS lookups — asn, whois, reverseDns, forwardDns, mxRecords
• Domain age checker — domainAge, domainAgeBatch
• Errors, rate limits & usage — error types, rateLimit, usageSummary

Methods

Every method maps to one ip-api.io endpoint and its product page:

| Method | Endpoint | Product page | |---|---|---| | lookup(ip?) | GET /api/v1/ip[/{ip}] | IP geolocation | | lookupBatch(ips) | POST /api/v1/ip/batch (≤100 IPs) | Bulk IP lookup | | emailInfo(email) | GET /api/v1/email/{email} | Email validation | | validateEmail(email) | GET /api/v1/email/advanced/{email} | Advanced email validation | | validateEmailBatch(emails) | POST /api/v1/email/advanced/batch (≤100) | Email list cleaning | | riskScore(ip?) | GET /api/v1/risk-score[/{ip}] | Risk score | | emailRiskScore(email) | GET /api/v1/risk-score/email/{email} | Fraud detection | | ipReputation(ip) | GET /api/v1/ip-reputation/{ip} | IP reputation | | torCheck(ip) | GET /api/v1/tor/{ip} | Tor detection | | asn(ip) | GET /api/v1/asn/{ip} | ASN lookup | | whois(domain) | GET /api/v1/dns/whois/{domain} | WHOIS lookup | | reverseDns(ip) | GET /api/v1/dns/reverse/{ip} | Reverse DNS | | forwardDns(hostname) | GET /api/v1/dns/forward/{hostname} | — | | mxRecords(domain) | GET /api/v1/dns/mx/{domain} | MX record lookup | | domainAge(domain) | GET /api/v1/domain/age/{domain} | Domain age checker | | domainAgeBatch(domains) | POST /api/v1/domain/age/batch | Domain age checker | | rateLimit() | GET /api/v1/ratelimit | — | | usageSummary() | GET /api/v1/usage/summary | — |

All responses are fully typed (IpInfo, RiskScore, AdvancedEmailValidation, …) and exported from the package.

Error handling

The client throws typed errors and never retries — on 429, RateLimitError.reset tells you when your quota renews:

import { IpApiClient, RateLimitError, AuthenticationError } from "ip-api-io";

const client = new IpApiClient({ apiKey: "YOUR_API_KEY" });
try {
  await client.lookup("8.8.8.8");
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`limit=${error.limit} remaining=${error.remaining} resetsAt=${error.reset}`);
  } else if (error instanceof AuthenticationError) {
    console.log("invalid API key");
  }
}

See docs/error-handling.md for the full error taxonomy.

Links

• Website: https://ip-api.io
• API reference: https://ip-api.io/api-docs.html
• OpenAPI spec: https://ip-api.io/openapi.json
• Get a free API key: https://ip-api.io

ip-api-io is the official client for ip-api.io. It is not affiliated with ip-api.com or ipapi.com.