The official JavaScript client for the WhoisFreaks WHOIS API. Look up live WHOIS records for any domain across 1,529+ TLDs, pull WHOIS history back to 1986, search registrants with reverse WHOIS and run bulk WHOIS lookups from JavaScript code.
The same package covers the DNS lookup API, domain availability API, typosquatting API, SSL certificate API, IP geolocation and IP reputation.
A live WHOIS lookup returns structured JSON like this (trimmed):
{
"status": true,
"domain_name": "whoisfreaks.com",
"domain_registered": "yes",
"create_date": "2019-03-19",
"update_date": "2026-02-17",
"expiry_date": "2027-03-19",
"domain_registrar": {
"iana_id": "1068",
"registrar_name": "NAMECHEAP INC",
"normalized_name": "namecheap, inc.",
"website_url": "http://www.namecheap.com"
},
"registrant_contact": {
"city": "Lewes",
"state": "Delaware",
"zip_code": "19958",
"country_name": "United States",
"country_code": "US"
},
"name_servers": ["albert.ns.cloudflare.com", "sue.ns.cloudflare.com"],
"domain_status": ["clienttransferprohibited"]
}- Installation
- Get an API key
- WHOIS lookup
- Normalized registrar, address and date fields
- Bulk WHOIS lookup
- WHOIS history
- Reverse WHOIS
- DNS lookup
- Domain availability check
- Typosquatting detection
- Error handling
- All endpoints
- Requirements
- Support
npm install whoisfreaks-jsCreate a free account at billing.whoisfreaks.com/signup. New accounts get 500 free credits with no credit card, usable across the live WHOIS, WHOIS history and reverse WHOIS APIs.
Keep the key out of source control. The examples read it from an environment variable:
export WHOISFREAKS_API_KEY="your_api_key"Every example below assumes this setup:
const WhoisFreaks = require('whoisfreaks-js');
const client = WhoisFreaks.ApiClient.instance;
client.authentications['ApiKeyAuth'].apiKey = process.env.WHOISFREAKS_API_KEY;Put the setup and one example in a .js file and run it with node. CommonJS has no top-level await, so each example runs inside an async function main().
Each request queries WHOIS servers and RDAP live, so you get the current record rather than a cached copy. One lookup costs 1 credit.
async function main() {
const record = await new WhoisFreaks.WHOISApi().whoisLive('whoisfreaks.com');
console.log(record.create_date, record.expiry_date); // 2019-03-19 2027-03-19
console.log(record.domain_registrar.registrar_name); // NAMECHEAP INC
console.log(record.name_servers);
}
main();Registries and registrars write the same facts in different formats. The API returns normalized fields so records from different TLDs line up without your own parsing code.
| What you get | Field | Example |
|---|---|---|
| One registrar name, however the registry spells it | domain_registrar.normalized_name |
namecheap, inc. for both "NAMECHEAP INC" and "NameCheap, Inc" |
| A parsed and geocoded contact address | registrant_contact.street, city, state, zip_code, country_name, country_code |
Lewes, Delaware, 19958, United States, US |
| One date format | create_date, update_date, expiry_date |
2019-03-19 |
async function main() {
const record = await new WhoisFreaks.WHOISApi().whoisLive('whoisfreaks.com');
const registrant = record.registrant_contact;
console.log(record.domain_registrar.normalized_name); // namecheap, inc.
console.log(registrant.city, registrant.state); // Lewes Delaware
console.log(registrant.country_code); // US
}
main();Use these fields to group a domain portfolio by registrar, filter registrants by country code or sort domains by expiry date across every TLD.
Look up to 100 domains in one call.
async function main() {
const request = WhoisFreaks.BulkWhoisRequest.constructFromObject({
domainNames: ['example.com', 'whoisfreaks.com', 'github.com'],
});
const result = await new WhoisFreaks.WHOISApi().bulkWhois(request);
}
main();For larger jobs, the Bulk WHOIS API accepts file uploads of up to 3M domains.
Get every recorded ownership change for a domain in one request. A new record is stored only when the WHOIS data changed, and history goes back to 1986.
async function main() {
const history = await new WhoisFreaks.WHOISApi().whoisHistory('whoisfreaks.com');
}
main();Find every domain registered with a keyword, such as a company name or registrant email, across 4.5B+ WHOIS records.
async function main() {
const matches = await new WhoisFreaks.WHOISApi().whoisReverse('whoisfreaks', { page: 1 });
}
main();Pull live DNS records for a domain. Pass all or a comma-separated list of record types: A, AAAA, MX, NS, TXT, SOA, SPF, CNAME.
async function main() {
const records = await new WhoisFreaks.DNSApi().dnsLive('A,MX,TXT', { domainName: 'whoisfreaks.com' });
}
main();The same class also covers bulk DNS, historical DNS and reverse DNS lookups.
Check whether a domain is registered and, with suggestions turned on, get up to 100 available alternatives on other TLDs.
async function main() {
const result = await new WhoisFreaks.DomainAvailabilityApi().domainAvailabilityV2('whoisfreaks.io', {
sug: true,
count: 5,
});
}
main();Find registered domains that look like typo variants of a brand name. Search by a brand keyword, or by a wildcard pattern such as whois* (up to 3 asterisks). Results come 100 domains per page with registration date, expiry date and drop status, across 1,529+ TLDs.
async function main() {
const typos = await new WhoisFreaks.TyposquattingApi().typosquatting({ keyword: 'whoisfreaks' });
}
main();To get the next page, pass the nextPageToken value from the response as pageToken, along with the same keyword or pattern.
Failed requests reject with a plain object rather than an Error. error.status holds the HTTP status code, error.body the parsed JSON error body and error.response the full HTTP response. A network failure or timeout has no status; the cause is in error.error.
async function main() {
try {
const record = await new WhoisFreaks.WHOISApi().whoisLive('whoisfreaks.com');
} catch (error) {
console.error(error.status, error.body);
}
}
main();Live API uptime and incident history are on the status page.
All URIs are relative to https://api.whoisfreaks.com, except database file status and downloads, which use https://files.whoisfreaks.com. Each method links to its parameters and response model.
| Class | Method | HTTP request | Description |
|---|---|---|---|
| WhoisFreaks.WHOISApi | bulkWhois | POST /v2.0/bulkwhois/live | Bulk WHOIS Lookup |
| WhoisFreaks.WHOISApi | whoisHistory | GET /v2.0/whois/history | Historical WHOIS records for a domain |
| WhoisFreaks.WHOISApi | whoisLive | GET /v2.0/whois/live | Live WHOIS Lookup |
| WhoisFreaks.WHOISApi | whoisReverse | GET /v2.0/whois/reverse | Reverse WHOIS lookup by keyword |
| WhoisFreaks.ASNWHOISApi | asnWhois | GET /v2.0/asn-whois | ASN WHOIS Lookup |
| WhoisFreaks.IPWHOISApi | ipWhois | GET /v1.0/ip-whois | IP WHOIS Lookup |
| Class | Method | HTTP request | Description |
|---|---|---|---|
| WhoisFreaks.DNSApi | dnsBulk | POST /v2.0/dns/bulk/live | Bulk DNS Lookup |
| WhoisFreaks.DNSApi | dnsHistorical | GET /v2.0/dns/historical | Historical DNS Lookup |
| WhoisFreaks.DNSApi | dnsLive | GET /v2.0/dns/live | Live DNS Lookup |
| WhoisFreaks.DNSApi | dnsReverse | GET /v2.1/dns/reverse | Reverse DNS Lookup |
| WhoisFreaks.SSLApi | sslLookup | GET /v1.0/ssl/live | SSL Certificate Lookup |
| WhoisFreaks.SubdomainsApi | subdomains | GET /v1.0/subdomains | Subdomains Lookup |
| Class | Method | HTTP request | Description |
|---|---|---|---|
| WhoisFreaks.DomainAvailabilityApi | bulkDomainAvailabilityV2 | POST /v2.0/domain/availability | Bulk Domain Availability Check |
| WhoisFreaks.DomainAvailabilityApi | domainAvailabilityV2 | GET /v2.0/domain/availability | Domain Availability Check with Suggestions |
| WhoisFreaks.TyposquattingApi | typosquatting | GET /v3.0/domain/typos | Typosquatting Lookup |
| WhoisFreaks.DomainReputationApi | domainReputation | GET /v1/domain/security | Domain Reputation Lookup |
| Class | Method | HTTP request | Description |
|---|---|---|---|
| WhoisFreaks.GeolocationApi | bulkGeolocation | POST /v1.0/geolocation | Bulk IP Geolocation |
| WhoisFreaks.GeolocationApi | geolocation | GET /v1.0/geolocation | IP Geolocation Lookup |
| WhoisFreaks.IPReputationApi | bulkIpReputation | POST /v1.0/security | Bulk IP Reputation |
| WhoisFreaks.IPReputationApi | ipReputation | GET /v1.0/security | IP Reputation Lookup |
| Class | Method | HTTP request | Description |
|---|---|---|---|
| WhoisFreaks.AccountApi | accountUsage | GET /v1.0/whoisapi/usage | Account Usage |
| WhoisFreaks.AccountApi | databaseFileStatus | GET /v3.4/status | Database File Status (Public) |
| WhoisFreaks.AccountApi | rotateApiKey | GET /v1.0/api-key/rotate | Rotate API Key |
WHOIS, DNS, subdomain, IP, newly registered, expiring and dropped domain databases, plus the phishing, malware and spam threat feeds, are available through the Databases* classes. See the full method list for every download and status endpoint.
A download resolves with the file's bytes exactly as served: a Buffer in Node.js, a Blob in browsers. The whole file is buffered in memory before the call resolves. To save it to disk:
const fs = require('fs');
async function main() {
const file = await new WhoisFreaks.DatabasesWHOISApi().dbWhoisDaily();
fs.writeFileSync('whois-daily.csv', file);
}
main();Node.js 18 or later. The package also builds for the browser with webpack or browserify.
- WHOIS API documentation: whoisfreaks.com/documentation/whois-api
- All API documentation: whoisfreaks.com/documentation
- Product page: WhoisFreaks WHOIS API
- API status: status.whois.whoisfreaks.com
- Email: support@whoisfreaks.com
- Quick start: WHOIS API examples
- Other languages: Python, JavaScript, TypeScript, Java, Go, C#, Ruby, PHP, Swift, Kotlin
MIT. See LICENSE.