适用场景Whois 查询是互联网基础服务之一用于获取域名的准备信息包括准备商、准备主体、创建时间、到期时间、DNS 服务器等。在实际业务中以下场景经常会用到 Whois API域名查看文档前调查检查目标域名是否已被准备并获取其准备状态和到期时间辅助决策。域名监控与告警对已持有的域名定期查询在到期前 30 天内触发告警避免域名过期丢失。安全分析通过 Whois 信息追踪域名归属、准备商变更记录排查恶意域名。域名信息展示在后台管理系统或用户前端展示域名的准备详情如创建域龄、准备商等。接口能力边界该 Whois 查询接口封装了上游数据源并提供多项自动化处理能力开发者可以直接使用而无需自行处理复杂逻辑全 TLD 覆盖支持 .com、.cn、.net、.org、.io、.me、.top、.xyz 等几乎所有 ICANN 认证后缀。自动 URL 归一化传入https://www.baidu.com/abc时接口会自动剥离协议前缀、www 子域名、路径和端口仅保留顶级域名如baidu.com。域名可用性检测未准备域名返回is_availabletrue可用于域名抢注前的快速探测。到期告警当域名距离到期不足 30 天时expiring_soon字段为true便于前端或告警系统做出高亮提示。域龄友好显示creation_age_text直接返回“N 年 M 月”格式字符串无需开发者自行计算时间差。国内 .cn 中文主体对于 .cn 域名上游数据源返回中文准备主体名称如公司全称方便国内用户识别。缓存策略同一域名每天只调用一次上游后续查询直接返回缓存结果缓存有效期 24 小时既节省上游配额也避免频繁调用导致的封禁风险。错误字段修正源码已修复上游错误统一返回error字段而非message便于排查真实失败原因。请求方式与鉴权接口采用 HTTP GET 方法需要将 API Key 放在请求头X-API-Key中传递。请求地址https://v1.apizero.cn/api/whois请求方法GETQPS 限制5 次/秒建议控制调用频率避免限流。请求参数参数名必填类型说明示例domain是string待查询的域名。无需携带协议前缀、子域名、路径或端口接口会自动归一化处理。baidu.comwith_raw否boolean是否返回原始 Whois 文本raw_whois字段。默认为false建议仅在调试时启用。false注意domain参数支持传入www.baidu.com或https://www.baidu.com/path等格式接口会先尝试提取有效主域名若提取失败则会返回错误。推荐在客户端自行校验后仅传入裸域名。curl 请求示例以下示例调用查询域名apizero.cn的 Whois 信息需要将$APIZERO_API_KEY替换为你的真实 API Keycurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/whois?domainapizero.cn也可以使用 Python 的requests库import requests API_KEY your_api_key_here url https://v1.apizero.cn/api/whois params {domain: apizero.cn} headers {X-API-Key: API_KEY} response requests.get(url, paramsparams, headersheaders) print(response.json())使用 JavaScript (Node.js) 的fetchconst API_KEY your_api_key_here; const url new URL(https://v1.apizero.cn/api/whois); url.searchParams.set(domain, apizero.cn); fetch(url, { headers: { X-API-Key: API_KEY } }) .then(res res.json()) .then(data console.log(data));响应字段详解成功响应返回 HTTP 200 状态码JSON 主体格式如下已格式化展示{ code: 0, msg: 成功, request_id: abc123def456, data: { domain: baidu.com, suffix: com, registrar: MarkMonitor Information Technology (Shanghai) Co., Ltd., registrar_url: http://markmonitor.com, registrar_abuse_email: abusecomplaintsmarkmonitor.com, registrar_abuse_phone: 1.2083895740, whois_server: whois.markmonitor.com, creation_time: 1999-10-11 19:05:17, expiration_time: 2028-10-11 19:05:17, creation_age_text: 26 年 7 个月, creation_days: 9704, valid_days: 888, domain_status: [ clientDeleteProhibited 注册商设置禁止删除, clientTransferProhibited 注册商设置禁止转移 ], name_servers: [ NS1.BAIDU.COM, NS2.BAIDU.COM, NS3.BAIDU.COM ], dnssec: unsigned, registrant: , registrant_email: , is_available: false, is_expired: false, expiring_soon: false, query_time: 2026-05-07 09:18:54 } }顶层字段字段类型说明codeint业务状态码0表示成功非零表示失败。请以code为准而非 HTTP 状态码。msgstring提示信息成功时为“成功”失败时描述具体原因。request_idstring请求标识可用于日志追踪和排查问题。dataobject包含 Whois 详细信息的对象。data 字段详解字段类型说明domainstring查询的裸域名归一化后。suffixstring顶级域后缀如com、cn。registrarstring准备商名称。registrar_urlstring准备商官方网址。registrar_abuse_emailstring准备商滥用投诉邮箱。registrar_abuse_phonestring准备商滥用投诉电话。whois_serverstring提供 Whois 数据的服务器地址。creation_timestring域名准备时间UTC8。expiration_timestring域名到期时间UTC8。creation_age_textstring域龄易读文本如“26 年 7 个月”。creation_daysint从准备到查询日的总天数。valid_daysint距离到期的剩余天数。domain_statusarray域名状态列表每个元素附带中文解释。如clientDeleteProhibited。name_serversarrayDNS 服务器地址列表。dnssecstringDNSSEC 状态常见值unsigned、signed。registrantstring准备主体个人或组织名称。对于 .cn 域名返回中文名称部分域名可能因隐私保护而返回空字符串。registrant_emailstring准备人邮箱通常因隐私保护为空。is_availablebool域名是否未准备可用于查看文档。is_expiredbool域名是否已过期。expiring_soonbool域名是否在 30 天内到期可用于告警。query_timestring接口响应的时间点UTC8。常见错误与处理接口返回的 HTTP 状态码通常为 200无论业务是否成功。因此判断成功与否应检查 JSON 中的code字段。若code不为 0则msg或error字段包含错误详情。已知的错误场景错误原因可能的 code描述API Key 无效或未提供401请求头X-API-Key缺失或错误。QPS 超限429每秒请求超过 5 次请降低频率或使用令牌桶限流。参数domain缺失或格式无效1001示例以实际文档为准未传入域名或域名无法解析提示invalid domain format。上游数据源异常500第三方 Whois 服务临时不可用可稍后重试。域名不存在未准备成功但is_availabletrue并非错误。无需特殊处理按业务需求使用该字段。注意接口返回的错误字段名是error而非message解析时需注意。例如{code:1001,error:domain parameter is required}。工程化注意事项在正式项目中集成该 API 时建议关注以下几点缓存策略由于 Whois 数据的变化以天为单位且接口本身已对同一域名做 24 小时缓存因此客户端无需重复调用。可以设计内存缓存或 Redis缓存的 Key 可以采用whois:{domain}格式TTL 设为 24 小时。收到is_availabletrue的域名可适当缩短缓存时间例如 1 小时以便及时获取可能的准备变化。QPS 控制接口限速为 5 次/秒。如果在循环中批量查询多个域名建议使用信号量或定时器确保每秒不超过 5 个请求。可以使用类似asyncio.Semaphore或rate-limiter库实现。域名归一化处理虽然接口会自行归一化但为了减少无效请求客户端建议先对用户输入做基础校检去掉http://、https://、www.、路径和端口提取“域名.后缀”格式。若用户输入localhost或 IP 地址应直接拒绝请求接口也会返回错误。隐私保护处理大部分域名由于 GDPR 或 ICANN 政策registrant和registrant_email字段可能为空或被隐匿。不要在 UI 中强制展示未提供的字段。到期告警逻辑利用expiring_soon和valid_days字段可以在前端显示“即将到期”的提醒。建议在后端任务中每天查询待监控域名若expiring_soontrue则发送通知。注意该接口的expiring_soon仅当剩余天数 ≤ 30 天且域名未过期时为true。错误重试对于返回 HTTP 5xx 或超时的请求可实现指数退避重试最多 3 次。对于 4xx 错误则不重试直接记录日志并提示用户。费用控制由于未提供调用次数限制信息部署前请确认账户余额或配额说明。同时利用缓存减少不必要的调用避免浪费。参考文档接口文档含更多语言示例与字段说明https://apizero.cn/aidocs/whois原始 Markdown 文档https://apizero.cn/aidocs/whois/raw.md