API Documentation

v3.35

Next Whois provides a simple REST API for programmatic WHOIS/RDAP lookups and dynamic OG image generation. All endpoints are publicly accessible and require no authentication.

Quick Navigation

API Key WHOIS DNS Records DNS TXT SSL IP / ASN OG Image ICP Rate Limits

API Key Auth

Overview

When the administrator enables API Key verification, all public APIs (WHOIS, DNS, SSL, IP lookup) require a valid API Key in the request, otherwise HTTP 401 is returned.

Passing Methods

Request Header (recommended)

curl "https://www.x.rw/api/lookup?query=example.com" \
  -H "X-API-Key: rwh_your_key_here"

URL Query Parameter (fallback)

curl "https://www.x.rw/api/lookup?query=example.com&key=rwh_your_key_here"

Permission Scopes

Scope Value	Covered APIs
api	WHOIS/RDAP, DNS records, SSL certificate, IP/ASN lookup
subscription	Domain expiry subscription reminder APIs
all	All API features

Error Responses

HTTP Status	Reason
401	No API Key provided
403	Key invalid, disabled, expired or insufficient permissions

WHOIS & Lookup

GET

/api/lookup

Unified lookup endpoint supporting domain WHOIS/RDAP, IPv4, IPv6, ASN (autonomous system), and CIDR subnet — auto-detects input format and routes to the appropriate protocol.

Parameters

Parameter	Type	Required	Default	Description
query	string	Required	—	Query: domain / IPv4 / IPv6 / ASN (e.g. AS15169) / CIDR (e.g. 1.1.1.0/24)

Query Types · Example Requests

Domain (WHOIS / RDAP preferred)

curl "https://www.x.rw/api/lookup?query=google.com"

IPv4 Address

curl "https://www.x.rw/api/lookup?query=8.8.8.8"

IPv6 Address

curl "https://www.x.rw/api/lookup?query=2001:4860:4860::8888"

ASN (Autonomous System Number)

curl "https://www.x.rw/api/lookup?query=AS15169"

CIDR Subnet

curl "https://www.x.rw/api/lookup?query=1.1.1.0/24"

Success Response — Domain Lookup

{
  "status": true,
  "time": 1.23,
  "cached": false,
  "source": "rdap",
  "result": {
    "domain": "google.com",
    "registrar": "MarkMonitor Inc.",
    "registrarURL": "http://www.markmonitor.com",
    "ianaId": "292",
    "whoisServer": "whois.markmonitor.com",
    "creationDate": "1997-09-15T04:00:00Z",
    "expirationDate": "2028-09-14T04:00:00Z",
    "updatedDate": "2019-09-09T15:39:04Z",
    "status": [
      { "status": "clientDeleteProhibited", "url": "..." },
      { "status": "clientTransferProhibited", "url": "..." }
    ],
    "nameServers": ["ns1.google.com", "ns2.google.com", "ns3.google.com", "ns4.google.com"],
    "dnssec": "unsigned",
    "domainAge": 28,
    "remainingDays": 945,
    "rawWhoisContent": "Domain Name: GOOGLE.COM
Registry Domain ID: ...",
    "rawRdapContent": "{
  "objectClassName": "domain",
  ...
}"
  }
}

Success Response — IP / ASN Lookup

{
  "status": true,
  "time": 0.87,
  "cached": false,
  "source": "rdap",
  "result": {
    "domain": "8.8.8.8",
    "registrar": "ARIN",
    "cidr": "8.8.8.0/24",
    "country": "US",
    "creationDate": "1992-12-01T00:00:00Z",
    "status": [{ "status": "active", "url": "" }],
    "nameServers": [],
    "rawRdapContent": "..."
  }
}

Error Response

{
  "status": false,
  "time": 0.45,
  "error": "No match for domain "EXAMPLE.INVALID""
}

Notes

Domain lookup prefers RDAP protocol, falls back to WHOIS on failure; the source field indicates the protocol used
Cache hit: cached: true, time: 0; cache TTL: s-maxage=3600
IP / ASN / CIDR queries are routed via IANA RDAP bootstrap to the corresponding regional registry (ARIN / RIPE / APNIC etc.)
Rate limiting: max 40 requests per IP per minute; exceeding returns HTTP 429

DNS Tools

GET

/api/dns/records

Query any DNS records in parallel via four DoH resolvers (Google, Cloudflare, Quad9, AdGuard), returning deduplicated merged results and per-resolver latency.

Parameters

Parameter	Type	Required	Default	Description
name	string	Required	—	Domain to query, e.g. google.com or _dmarc.google.com
type	string	Optional	A	Record type: A · AAAA · MX · NS · CNAME · TXT · SOA · CAA · SRV

Example Request

curl "https://www.x.rw/api/dns/records?name=google.com&type=MX"

curl "https://www.x.rw/api/dns/records?name=google.com&type=AAAA"

curl "https://www.x.rw/api/dns/records?name=_dmarc.google.com&type=TXT"

Success Response

{
  "name": "google.com",
  "type": "MX",
  "found": true,
  "records": [
    { "priority": 10, "exchange": "smtp.google.com" }
  ],
  "flat": ["10 smtp.google.com"],
  "resolvers": [
    { "name": "Google DoH",     "kind": "doh", "records": [...], "flat": [...], "latencyMs": 42 },
    { "name": "Cloudflare DoH", "kind": "doh", "records": [...], "flat": [...], "latencyMs": 38 },
    { "name": "Quad9 DoH",      "kind": "doh", "records": [...], "flat": [...], "latencyMs": 55 },
    { "name": "AdGuard DoH",    "kind": "doh", "records": [...], "flat": [...], "latencyMs": 61 }
  ],
  "latencyMs": 63
}

Notes

No caching (Cache-Control: no-store), data fetched in real time
TXT records return raw values; parse SPF / DMARC / DKIM / BIMI yourself
Record not found: found: false, flat: []
Single resolver timeout: 7s, four run in parallel, overall usually completes in 1–2s

GET

/api/dns/txt

Dedicated TXT record query, using four standard DNS resolvers (Google, Cloudflare, Quad9, OpenDNS) in parallel — ideal for verifying SPF, DMARC, DKIM and other email security configurations.

Parameters

Parameter	Type	Required	Default	Description
name	string	Required	—	Domain or subdomain to query, e.g. google.com or _dmarc.example.com

Example Request

# 查询 SPF 记录
curl "https://www.x.rw/api/dns/txt?name=google.com"

# 查询 DMARC 记录
curl "https://www.x.rw/api/dns/txt?name=_dmarc.google.com"

# 查询 DKIM 记录
curl "https://www.x.rw/api/dns/txt?name=google._domainkey.gmail.com"

Success Response

{
  "name": "google.com",
  "found": true,
  "records": [
    ["v=spf1 include:_spf.google.com ~all"],
    ["docusign=1b0a6754-49b1-4db5-8540-d2c12664b289"],
    ["globalsign-smime-dv=CDYX+XFHUw2wml6/Gb8+59BsH31KzUr6c1l2BPvqKX8="]
  ],
  "flat": [
    "v=spf1 include:_spf.google.com ~all",
    "docusign=1b0a6754-49b1-4db5-8540-d2c12664b289",
    "globalsign-smime-dv=CDYX+XFHUw2wml6/Gb8+59BsH31KzUr6c1l2BPvqKX8="
  ],
  "resolvers": [
    { "name": "Google DNS",  "records": [...], "flat": [...], "latencyMs": 18 },
    { "name": "Cloudflare",  "records": [...], "flat": [...], "latencyMs": 15 },
    { "name": "Quad9",       "records": [...], "flat": [...], "latencyMs": 23 },
    { "name": "OpenDNS",     "records": [...], "flat": [...], "latencyMs": 31 }
  ],
  "latencyMs": 35
}

Error Response / Not found

{
  "name": "_dmarc.example.invalid",
  "found": false,
  "records": [],
  "flat": [],
  "resolvers": [...],
  "latencyMs": 42,
  "error": "ENOTFOUND"
}

Differences from /api/dns/records?type=TXT

Feature	/api/dns/txt	/api/dns/records?type=TXT
Resolution Protocol	Standard DNS (UDP/TCP)	DoH (HTTPS-encapsulated)
Resolvers	8.8.8.8 / 1.1.1.1 / 9.9.9.9 / 208.67.222.222	Google / Cloudflare / Quad9 / AdGuard DoH
Use Case	Email security verification (SPF/DMARC/DKIM)	General DNS record queries, supports more types

SSL Certificate

GET

/api/ssl/cert

Connects directly to the target host (default port 443), performs a TLS handshake and returns SSL certificate details: validity period, issuer, SAN list, certificate chain, cipher suites, and days remaining.

Parameters

Parameter	Type	Required	Default	Description
hostname	string	Required	—	Target hostname or IP, e.g. google.com, github.com or 1.1.1.1
port	number	Optional	443	Target TLS port (default 443, SMTPS uses 465, IMAPS uses 993, etc.)

Example Request

curl "https://www.x.rw/api/ssl/cert?hostname=github.com"

# 检测非标准端口
curl "https://www.x.rw/api/ssl/cert?hostname=mail.example.com&port=465"

Success Response

{
  "ok": true,
  "hostname": "github.com",
  "port": 443,
  "authorized": true,
  "authError": null,
  "protocol": "TLSv1.3",
  "cipher": "TLS_AES_128_GCM_SHA256",
  "subject": { "CN": "github.com", "O": "GitHub, Inc.", "C": "US" },
  "issuer": { "CN": "DigiCert TLS Hybrid ECC SHA384 2020 CA1", "O": "DigiCert Inc" },
  "valid_from": "2024-03-07T00:00:00.000Z",
  "valid_to": "2025-03-07T23:59:59.000Z",
  "days_remaining": 120,
  "is_expired": false,
  "is_expiring_soon": false,
  "fingerprint256": "AA:BB:CC:...",
  "serialNumber": "0A:1B:2C:...",
  "sans": [
    { "type": "DNS", "value": "github.com" },
    { "type": "DNS", "value": "www.github.com" }
  ],
  "chain": [
    { "subject": "CN=DigiCert...", "issuer": "CN=...", "valid_to": "..." }
  ],
  "latencyMs": 185
}

Error Response

{
  "ok": false,
  "hostname": "expired.badssl.com",
  "port": 443,
  "authorized": false,
  "authError": "certificate has expired",
  "error": "certificate has expired",
  "latencyMs": 210
}

Notes

Certificate chain includes complete intermediate CA info from server to root CA
Connection timeout: 10s; unreachable hosts return ok: false + error field

IP & ASN Lookup

GET

/api/ip/lookup

Queries IP geolocation, ASN, ISP, organization, and routing information for IPv4/IPv6 addresses or ASN numbers.

Parameters

Parameter	Type	Required	Default	Description
q	string	Required	—	IPv4 address, IPv6 address, or ASN number (e.g. 8.8.8.8, 2001:db8::1, AS15169)

Example Request

# IPv4 地址
curl "https://www.x.rw/api/ip/lookup?q=8.8.8.8"

# IPv6 地址
curl "https://www.x.rw/api/ip/lookup?q=2001:4860:4860::8888"

# 主机名（自动解析为 IP 再查询）
curl "https://www.x.rw/api/ip/lookup?q=dns.google"

# ASN 归属网段
curl "https://www.x.rw/api/ip/lookup?q=AS15169"

Success Response

{
  "type": "ipv4",
  "query": "8.8.8.8",
  "resolvedFrom": null,
  "flag": "🇺🇸",
  "country": "United States",
  "countryCode": "US",
  "region": "California",
  "city": "Mountain View",
  "timezone": "America/Los_Angeles",
  "offset": -28800,
  "lat": 37.4056,
  "lon": -122.0775,
  "isp": "Google LLC",
  "org": "AS15169 Google LLC",
  "as": "AS15169 Google LLC",
  "asname": "GOOGLE",
  "reverse": "dns.google",
  "mobile": false,
  "proxy": false,
  "hosting": true,
  "rdap": {
    "name": "GOGL",
    "handle": "NET-8-8-8-0-1",
    "startAddress": "8.8.8.0",
    "endAddress": "8.8.8.255",
    "ipVersion": "v4",
    "contact_org": "Google LLC"
  }
}

Notes

Geolocation data from MaxMind GeoLite2, ASN data from routeviews
ASN query returns all prefixes announced by the AS
Private IP addresses and reserved ranges return limited information
Cache TTL: s-maxage=86400 (24h)

Tools API

GET

/api/og

Generate a dynamic Open Graph image with WHOIS details. Internally queries /api/lookup and renders a card-style summary. Returns a PNG image.

Parameters

Parameter	Type	Required	Default	Description
query	string	Optional	—	Domain name, IP, ASN, or CIDR to look up and display. Alias: q
w	number	Optional	1200	Image width in pixels (200-4096)
h	number	Optional	630	Image height in pixels (200-4096)
theme	string	Optional	light	Color theme: "light" or "dark"

Example Request

curl "https://www.x.rw/api/og?query=google.com&theme=dark" -o og.png

# 自定义尺寸（适合 Twitter Card）
curl "https://www.x.rw/api/og?query=example.com&w=1200&h=600" -o card.png

Preview

/api/og?query=google.com

ICP Filing Query

GET

/api/icp/query

Query ICP filing records for Chinese mainland websites and apps. Supports domain lookup, app/mini-program filing, and blacklist queries.

Parameters

Parameter	Type	Required	Default	Description
type	string	Required	—	Query type
search	string	Required	—	Domain name or ICP number to query
pageNum	number	Optional	1	Page number (default 1)
pageSize	number	Optional	10	Page number (default 1)

Query Type Reference

type	Description	Parameter
web	Website	Normal Filing
app	APP	Normal Filing
mapp	Mini Program	Normal Filing
kapp	Quick App	Normal Filing
bweb	Illegal Website	Blacklist
bapp	Illegal APP	Blacklist
bmapp	Illegal Mini Program	Blacklist
bkapp	Illegal Quick App	Blacklist

Example Request

Domain (WHOIS / RDAP preferred)

curl "https://www.x.rw/api/icp/query?type=web&search=baidu.com"

Domain name or ICP number to query

curl "https://www.x.rw/api/icp/query?type=web&search=京ICP证030173号"

Unit name

curl "https://www.x.rw/api/icp/query?type=web&search=深圳市腾讯计算机系统有限公司&pageNum=2&pageSize=20"

Illegal APP

curl "https://www.x.rw/api/icp/query?type=bapp&search=example"

Success Response

{
  "ok": true,
  "type": "web",
  "search": "baidu.com",
  "pageNum": 1,
  "pageSize": 10,
  "total": 1,
  "pages": 1,
  "list": [
    {
      "domain": "baidu.com",
      "domainId": "12345678",
      "limitAccess": false,
      "mainLicence": "京ICP证030173号",
      "natureName": "企业",
      "serviceLicence": "京ICP备030173号",
      "unitName": "北京百度网讯科技有限公司",
      "updateRecordTime": "2023-09-01",
      "contentTypeName": "信息服务",
      "mainUnitAddress": "北京市海淀区上地十街10号",
      "cityId": "110100",
      "countyId": "110108"
    }
  ]
}

Response Fields

Parameter	Description
total / pages	Total records / total pages
domain	Filed domain
domainId	Domain ID
limitAccess	Whether access is restricted
mainLicence	ICP mainLicence
serviceLicence	ICP serviceLicence
natureName	Unit type (company / institution / individual etc.)
unitName	Unit name
updateRecordTime	Approval date
contentTypeName	Service pre-approval items / content type
mainUnitAddress	Main address
serviceName	Service name (APP, mini-program, or quick app name)
version	Service version
blackListLevel	Threat level (only for violation types; value 2 = no current violation)

Notes

ICP data from MIIT (Ministry of Industry and Information Technology) official API
Blacklist queries (types starting with b) require special permissions
Results are paginated; use the page parameter to fetch additional pages

Rate Limiting & Caching

API Endpoint	Rate Limit Rule	Cache
/api/lookup	40 req/IP/min (sliding window)	`s-maxage=3600`
/api/dns/records	60 req/IP/min	`no-store`
/api/dns/txt	60 req/IP/min	`no-store`
/api/ssl/cert	20 req/IP/min	`no-store`
/api/ip/lookup	30 req/IP/min	`no-store`
/api/icp/query	Unlimited	`no-store`
/api/og	Unlimited	`s-maxage=86400`

When /api/lookup hits cache: cached: true and time: 0. Exceeding limit returns HTTP 429 with X-RateLimit-Limit / Remaining / Reset headers.

X.RW v3.35 · GitHub