Whois 域名查询接口用于根据域名获取注册信息，包括注册商、注册主体、创建时间、到期时间、DNS 服务器、域名状态与 DNSSEC 等。对于域名管理后台、到期监控、批量资产盘点这类场景，它是常用的一次性查询能力。本文从零开始，说明第一次调用需要准备什么、最小请求怎么发、返回值怎么看。

适用场景与能力边界

典型用途包括：域名到期前的预警提醒；查询某个域名是否已被注册，为选名提供依据；批量拉取自有域名资产并汇总注册商与注册主体；在页面中展示域名的“域龄”。

接口支持所有主流 TLD，包括.com、.cn、.net、.org、.io、.me、.top、.xyz等几乎所有 ICANN 认证后缀。有一点值得注意：接口会自动归一化传入的地址，例如传入https://www.baidu.com/abc，会被自动剥离为baidu.com。这意味着调用方不必先写 URL 解析逻辑。

能力边界同样需要说清：Whois 数据反映的是注册局/注册商侧的公开记录，受隐私保护策略影响的域名，注册主体等字段可能被代理信息替代或为空；接口不提供域名解析结果、网站内容或流量数据。另外，Whois 数据年级变化，接口侧对同一域名做了 24 小时缓存，因此返回的是缓存窗口内的结果，不适合用来判断秒级状态变化。

调用前的准备

需要两样东西：一个域名，以及一个 API Key。

域名参数domain可以传裸域名，也可以传完整 URL，接口会自动归一化，但显式传裸域名更稳妥。第二个参数with_raw用于控制是否返回原始 Whois 文本，当只需要结构化字段时可以不传，以减小响应体积。

鉴权兼容Authorization: Bearer <API_KEY>请求头、X-API-Key请求头，或 Query 中的key参数。本文示例使用 Query 参数形式，便于 curl 直接复制。

最小请求：curl 示例

把YOUR_API_KEY替换为实际 Key，baidu.com替换为目标域名：

curl "https://v1.apizero.cn/api/whois?domain=baidu.com&key=YOUR_API_KEY"

需要原始文本时加上with_raw：

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://v1.apizero.cn/api/whois?domain=baidu.com&with_raw=true"

接口方法为 GET，参数通过 Query String 传递。

Python 接入示例

下面封装一个带超时、业务码判断与结果分流的调用函数：

import os import requests def query_whois(domain: str, with_raw: bool = False, api_key: str | None = None) -> dict: url = "https://v1.apizero.cn/api/whois" params = {"domain": domain} if with_raw: params["with_raw"] = "true" headers = {} key = api_key or os.environ.get("APIZERO_KEY") if key: headers["Authorization"] = f"Bearer {key}" resp = requests.get(url, params=params, headers=headers, timeout=20) resp.raise_for_status() payload = resp.json() if payload.get("code") != 0: # 注意：错误信息字段名为 error raise RuntimeError(f"查询失败: code={payload.get('code')}, error={payload.get('error')}") return payload["data"] data = query_whois("baidu.com") if data.get("is_available"): print("域名未注册") else: print("注册商:", data.get("registrar")) print("创建时间:", data.get("creation_date")) print("到期时间:", data.get("expiration_date")) print("域龄:", data.get("creation_age_text")) if data.get("expiring_soon"): print("警告：域名将在 30 天内到期")

这里有个容易踩坑的点：该接口错误响应中的字段名是error，不是常见的msg。解析失败响应时按error取值，否则会拿到None。

返回字段解读

成功响应的code == 0，核心数据在data内。字段含义如下（名称与结构以文档为准）：

两个字段值得单独说明。is_available让接口可以兼做域名可用性检测，未注册域名会返回 true，可用于选名前查询。expiring_soon在 30 天内到期时为 true，前端可以据此做高亮提示，省去自己算日期的麻烦。

关于中文主体：对国内.cn等域名，接口的 whoiscx 服务可能返回中文注册主体名，例如「极数本源（福州）科技有限公司」。但这并非所有域名都有，读取时仍要做空值判断，不能假设registrant或whoiscx必然非空。

with_raw=true时返回的原始 Whois 文本是各注册局格式不一的文本块，适合排查或留档，不适合直接做字段解析——结构化字段已经由接口整理好。

常见错误与排查

解析错误响应时记住字段是error。这条在接入阶段很容易被忽略，用惯了msg的代码会静默吞掉错误原因。

工程化注意事项

利用 24 小时缓存。接口对同一域名在 24 小时内只调用一次上游服务。业务侧若做批量盘点，不必担心对同一域名重复查询带来的额外开销，但也不要指望连续调用能观察到即时变化。

归一化不要完全依赖接口。虽然接口会自动剥离路径与协议，但在调用前用urllib.parse或简单正则统一成小写裸域名，能让本地缓存键更一致，避免Baidu.com与baidu.com在本地缓存中重复。

Key 保存在服务端。域名资产信息往往属于内部数据，由后端代理调用，前端只调用自己的业务接口。

到期告警不要只依赖单次查询。expiring_soon只反映查询时刻的 30 天窗口，配合定时任务周期性拉取，才能形成稳定的到期提醒链路。

原始文本谨慎落库。with_raw返回的文本可能包含注册人联系信息，属于个人信息范畴，存储前应评估必要性并做访问控制。

参考文档

• 接口文档
• 接口地址