WHOIS API: Domain Lookups as JSON with RDAP
Short answer: A WHOIS API gives you a domain's registrar, creation and expiry dates, status codes and nameservers as JSON instead of the free-form text that port 43 WHOIS prints. For most domains you don't need a paid service: the registries run RDAP, WHOIS's JSON successor, free over HTTPS, and since January 2025 it is the official source for every generic TLD. The catch is that many country-code TLDs (.io, .de, .tr, .eu and others) still have no RDAP, so a script that must handle any domain needs a WHOIS fallback and a parser. This post shows both: RDAP directly with curl and Python, and one API call that covers every TLD.
WHOIS and RDAP
WHOIS is a 1980s protocol: open a TCP connection to port 43, send the domain name, read back text. Every registry formats that text its own way. Verisign prints Registry Expiry Date:, DENIC prints no dates at all, the .tr registry uses its own blocks, and the server to ask changes per TLD (and for .com and .net, you have to follow a referral to the registrar's server for more).
RDAP (Registration Data Access Protocol, RFC 9083) answers the same question as JSON over HTTPS, with fixed field names. IANA publishes which server handles which TLD. On 28 January 2025 ICANN made RDAP the definitive source of registration data for generic TLDs; registries and registrars no longer have to run port 43 WHOIS at all (ICANN's announcement). New code should start with RDAP.
Got an idea? Find the perfect domain for it
Our AI domain name generator suggests available names across hundreds of extensions. Free SSL, DNS and Whois privacy included.
Free: call RDAP yourself
The quickest way is rdap.org, which redirects to the right registry server:
curl -sL https://rdap.org/domain/nameocean.net \
| jq -r '.events[] | select(.eventAction=="expiration") | .eventDate'
2027-01-10T08:34:46Z
In a program, skip the redirect and read IANA's bootstrap file once: it maps each TLD to its RDAP server. A 404 means the registry has no such domain.
import requests
BOOTSTRAP = "https://data.iana.org/rdap/dns.json"
_servers = None
def rdap_server(domain):
global _servers
if _servers is None:
_servers = {}
for tlds, urls in requests.get(BOOTSTRAP, timeout=10).json()["services"]:
for tld in tlds:
_servers[tld] = urls[0]
return _servers.get(domain.rsplit(".", 1)[-1])
def rdap(domain):
base = rdap_server(domain)
if base is None:
raise LookupError("no RDAP server for " + domain)
resp = requests.get(base.rstrip("/") + "/domain/" + domain,
headers={"Accept": "application/rdap+json"}, timeout=10)
if resp.status_code == 404:
return None # not registered
resp.raise_for_status()
return resp.json()
data = rdap("nameocean.net")
events = {e["eventAction"]: e["eventDate"] for e in data["events"]}
print(events["expiration"]) # 2027-01-10T08:34:46Z
print([ns["ldhName"] for ns in data["nameservers"]]) # ['NS1.NAMEOCEAN.NET', ...]
print(rdap("no-such-name-xq81z.com")) # None
rdap("nic.io") # LookupError: no RDAP server for nic.io
Where the usual WHOIS fields are in an RDAP answer:
| You want | RDAP field |
|---|---|
| Created, updated, expires | events[] with eventAction registration, last changed, expiration |
| Registrar and its IANA ID | the entry in entities[] whose roles include registrar: name in vcardArray (fn), ID in publicIds |
| Status | status[], as words: client transfer prohibited |
| Nameservers | nameservers[].ldhName |
| DNSSEC | secureDNS.delegationSigned |
Where it gets harder
- Not every TLD has RDAP. When we checked IANA's bootstrap file in November 2026, .com, .net, .org, .uk, .fr, .nl, .ai, .app and .dev were in it; .io, .de, .tr, .eu, .ru, .co, .me, .jp and .cn were not. For those you are back to port 43 and parsing text that differs per registry.
- Status codes have two spellings. RDAP writes
client transfer prohibited; WHOIS and EPP writeclientTransferProhibited, and RDAP'sactiveis EPP'sok(RFC 8056 has the mapping). Normalize before you compare. - Dates vary. Most RDAP servers use UTC with a
Z; some use an offset. Some ccTLD WHOIS servers give a date without a time (2027-Aug-22.) or no dates at all. - Contact data is mostly gone. Since GDPR, registrant names, emails and phone numbers are redacted for most domains. Neither WHOIS nor RDAP will tell you who owns a domain; the registrar's abuse contact is usually what is left.
- Rate limits. Registries throttle heavy users by IP, usually without publishing the limit. Cache answers; a domain's expiry date doesn't change by the minute.
One API call for any TLD
The NameOcean API has a WHOIS endpoint that does the above for you: RDAP when the TLD has it, otherwise the registry's WHOIS text, parsed into the same fields. It works for any domain, not only domains registered with us. You need a free NameOcean account and an API key with the domains:read scope (API keys need two-step login on the account).
curl https://nameocean.net/api/v1/whois/nameocean.net \
-H "Authorization: Bearer $NAMEOCEAN_API_KEY"
{
"name": "nameocean.net",
"registered": true,
"registrar": "1API GmbH",
"registrar_iana_id": "1387",
"created_at": "2019-01-10T08:34:46Z",
"updated_at": "2025-11-21T22:29:55Z",
"expires_at": "2027-01-10T08:34:46Z",
"status": ["clientTransferProhibited"],
"nameservers": ["ns1.nameocean.net", "ns2.nameocean.net", "ns3.nameocean.net", "ns4.nameocean.net"],
"dnssec": false,
"source": "rdap",
"server": "https://rdap.verisign.com/net/v1/"
}
For a TLD without RDAP the fields are the same, source is whois, and raw holds the registry's text in case you need a line we don't parse:
curl -s https://nameocean.net/api/v1/whois/nic.io -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
| jq -c '{registrar, expires_at, source, server}'
{"registrar":"Registry Operator acts as Registrar","expires_at":"2027-05-01T00:00:02Z","source":"whois","server":"whois.nic.io"}
- Status codes are always EPP names (
clientTransferProhibited,ok). A few ccTLDs use their own words (DENIC:connect; .tr:Active), which are passed through. - Dates are ISO 8601 in UTC, or a plain date when the registry gives no time. A field the registry doesn't publish is
null. "registered": falsemeans the registry has no such domain. To check whether you can buy it and for how much, use/domains/check.- Answers are cached for an hour. If the registry doesn't answer you get
502with"code": "registry_unavailable"; a malformed name gets400. The account limit is 120 requests a minute.
Example: warn before domains expire
Domains registered at different registrars, some on ccTLDs: this prints the ones that expire within 30 days.
import os
from datetime import datetime, timedelta, timezone
import requests
API = "https://nameocean.net/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["NAMEOCEAN_API_KEY"]}
DOMAINS = ["nameocean.net", "nic.io", "denic.de"]
soon = datetime.now(timezone.utc) + timedelta(days=30)
for name in DOMAINS:
resp = requests.get(f"{API}/whois/{name}", headers=HEADERS, timeout=30)
resp.raise_for_status()
info = resp.json()
expires = info["expires_at"]
if expires is None:
print(f"{name}: the registry does not publish an expiry date ({info['source']})")
continue
when = datetime.fromisoformat(expires.replace("Z", "+00:00"))
if when.tzinfo is None: # some ccTLDs give a date only
when = when.replace(tzinfo=timezone.utc)
flag = "EXPIRES SOON" if when < soon else "ok"
print(f"{name}: {expires} via {info['registrar']} [{flag}]")
Run it from cron once a day. denic.de shows the limit of any WHOIS API: DENIC's public WHOIS has no expiry date to return.
From an AI assistant
The same lookup is a tool in NameOcean's remote MCP server, whois_domain. After claude mcp add --transport http nameocean https://nameocean.net/mcp, you can ask Claude Code or another MCP client "when does example.io expire and who is the registrar?" and it calls the tool instead of guessing.
Which one to use
| RDAP directly | NameOcean /whois | |
|---|---|---|
| Cost | Free | Free with an account |
| Key needed | No | Yes (domains:read) |
| TLDs without RDAP (.io, .de, .tr…) | Not covered | Parsed from WHOIS, text in raw |
| Status codes | RDAP words, map them yourself | EPP names |
| Caching and retries | Yours to build | 1-hour cache, RDAP then WHOIS |
If you only look up gTLDs, call RDAP directly: it is free and needs nothing from us. If your list includes ccTLDs, or you'd rather get one JSON shape for every domain, use the API.
Links
- NameOcean API reference (the
/whois/{name}endpoint and its schema) - IANA RDAP bootstrap file for domains
- RFC 9083: JSON responses for RDAP
- RFC 8056: EPP and RDAP status mapping
- ICANN: Launching RDAP; Sunsetting WHOIS (January 2025)
Got an idea? Find the perfect domain for it
Our AI domain name generator suggests available names across hundreds of extensions. Free SSL, DNS and Whois privacy included.
Read in other languages: