Skip to content

README.md

Latest commit

 

History

History
152 lines (110 loc) · 4.67 KB

README.md

File metadata and controls

152 lines (110 loc) · 4.67 KB

RDAP API Node.js SDK

npm version Node.js License: MIT

Official Node.js SDK for the RDAP API — look up domains, IP addresses, ASNs, nameservers, and entities via the RDAP protocol.

Installation

npm install rdapapi

Quick start

import { RdapClient } from "rdapapi";

const client = new RdapClient("your-api-key");

// Domain lookup
const domain = await client.domain("google.com");
console.log(domain.registrar.name); // "MarkMonitor Inc."
console.log(domain.dates.expires); // "2028-09-14T04:00:00Z"
console.log(domain.nameservers); // ["ns1.google.com", ...]

// IP address lookup
const ip = await client.ip("8.8.8.8");
console.log(ip.name); // "GOGL"
console.log(ip.cidr); // ["8.8.8.0/24"]

// ASN lookup
const asn = await client.asn(15169);
console.log(asn.name); // "GOOGLE"

// Nameserver lookup
const ns = await client.nameserver("ns1.google.com");
console.log(ns.ipAddresses.v4); // ["216.239.32.10"]

// Entity lookup
const entity = await client.entity("GOGL");
console.log(entity.name); // "Google LLC"
console.log(entity.autnums[0].handle); // "AS15169"

client.close();

Bulk domain lookups

Look up multiple domains in a single request (Pro and Business plans). Up to 10 domains per call, with concurrent upstream fetches:

const result = await client.bulkDomains(["google.com", "github.com", "invalid..com"], {
  follow: true,
});

console.log(result.summary); // { total: 3, successful: 2, failed: 1 }

for (const r of result.results) {
  if (r.status === "success" && r.data) {
    console.log(`${r.data.domain}: ${r.data.registrar.name}`);
  } else {
    console.log(`${r.domain}: ${r.error}`);
  }
}

Each domain counts as one request toward your monthly quota. Starter plans receive a SubscriptionRequiredError (403).

Registrar follow-through

For thin registries like .com and .net, the registry only returns basic registrar info. Use follow: true to follow the registrar's RDAP link and get richer contact data:

const domain = await client.domain("google.com", { follow: true });
console.log(domain.entities.registrant?.organization); // "Google LLC"
console.log(domain.entities.registrant?.email); // "registrant@google.com"

Error handling

import { RdapClient, NotFoundError, RateLimitError, AuthenticationError } from "rdapapi";

const client = new RdapClient("your-api-key");

try {
  const domain = await client.domain("nonexistent.example");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Domain not found");
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof AuthenticationError) {
    console.log("Invalid API key");
  }
}

All exceptions inherit from RdapApiError and include statusCode, error, and message properties.

Exception HTTP Status When
ValidationError 400 Invalid input format
AuthenticationError 401 Missing or invalid API key
SubscriptionRequiredError 403 No active subscription
NotFoundError 404 No RDAP data found
RateLimitError 429 Rate limit or quota exceeded
UpstreamError 502 Upstream RDAP server error
TemporarilyUnavailableError 503 Domain data temporarily unavailable

Configuration

const client = new RdapClient("your-api-key", {
  baseUrl: "https://rdapapi.io/api/v1", // default
  timeout: 30_000, // milliseconds, default
});

TypeScript

The SDK is written in TypeScript with full type definitions. All response types are exported:

import type { DomainResponse, IpResponse, AsnResponse } from "rdapapi";

Requirements

Links

Development

Set up pre-commit hooks (runs lint + tests before each commit):

git config core.hooksPath .githooks

License

MIT