适用场景域名准备信息查询是域名管理中极高频率的操作。典型的业务场景包括域名到期监控定期检查自有域名是否临近到期提前通知续费避免业务中断。批量域名可用性检测在新项目筹备时批量查询备选域名是否被准备快速筛选可用域名。域名归属验证安全审计中需要确认某个域名的准备主体、准备商用于风险评估。域名状态跟踪监控域名是否处于 clientHold、clientTransferProhibited 等异常状态及时处理。Whois 原始文本存档在某些合规场景下需要保留完整的 whois 原始响应raw_whois供后续分析。无论是个人开发者维护几个域名还是企业运维上千个域名一个稳定、易用的 Whois 查询接口都能大幅提升工作效率。接口能力边界本 API 由apizero.cn提供核心能力如下支持主流 TLD几乎所有 ICANN 认证后缀包括.com、.cn、.net、.org、.io、.me、.top、.xyz等常见以及大多数小众后缀。自动归一化传入带协议、子域名或路径的地址如https://www.example.com/path接口会自动剥离为example.com进行查询无需预处理。域名可用性检测对于未准备域名响应中is_available字段为true可用于抢注前检测。到期预警若域名在 30 天内到期expiring_soon字段返回true便于前端高亮提示。域龄展示返回creation_age_text如“26 年 7 个月”和creation_days直观展示域龄。国内 .cn 域名中文主体上游 whoiscx 对cn后缀域名会返回中文准备单位名称如“某某科技有限公司”对国内业务友好。缓存策略Whois 数据属年级变化接口对同一域名 24 小时内只调用一次上游降低上游压力并提高响应速度。频率限制QPS每秒查询数为 5适用于中小规模集成高频场景需合理安排请求间隔或使用批处理。请求参数与鉴权请求方式方法GET地址https://v1.apizero.cn/api/whois鉴权通过 HTTP 头X-API-Key传递密钥密钥需从 apizero.cn 平台获取。查询参数参数名必填类型说明示例domain是string待查询域名。自动忽略 http(s)://、路径、端口、子域名www. 前缀由上游处理baidu.comwith_raw否boolean是否返回原始 whois 文本raw_whois字段约 3KB默认false建议调试时开启true注意传入domain时无需自行剥离www.上游已内置规范化处理。但建议清理掉 URL 中多余部分避免意外截断。curl 接入示例以下是一个完整的可复制 curl 示例请将$APIZERO_API_KEY替换为实际密钥curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/whois?domainbaidu.com若需要获取原始 Whois 文本可加上with_rawtruecurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/whois?domainbaidu.comwith_rawtruePython 代码接入在实际工程中通常使用 Python 等语言进行自动化调用。下面是一个完整的封装函数包含错误处理与超时控制import requests import time def query_whois(domain: str, api_key: str, with_raw: bool False) - dict: 查询域名 Whois 信息 :param domain: 域名如 example.com :param api_key: API 密钥 :param with_raw: 是否获取原始 Whois 文本 :return: 解析后的 JSON 字典 :raises: 请求异常或 API 返回错误时抛出 url https://v1.apizero.cn/api/whois headers {X-API-Key: api_key} params {domain: domain, with_raw: str(with_raw).lower()} try: resp requests.get(url, headersheaders, paramsparams, timeout10) resp.raise_for_status() # 检查 HTTP 状态码 data resp.json() # 自定义错误API 返回码非 0 if data.get(code) ! 0: error_msg data.get(error, data.get(msg, 未知错误)) raise RuntimeError(fAPI 返回错误: {error_msg}) return data[data] except requests.exceptions.RequestException as e: raise RuntimeError(f网络请求失败: {e}) # 使用示例 if __name__ __main__: API_KEY your_api_key_here domain baidu.com try: result query_whois(domain, API_KEY, with_rawFalse) print(f域名: {result[domain]}) print(f注册商: {result[registrar]}) print(f创建时间: {result[creation_time]}) print(f到期时间: {result[expiration_time]}) print(f是否可用: {result[is_available]}) print(f域名状态: {result[domain_status]}) except Exception as e: print(f查询失败: {e})注意代码中使用了str(with_raw).lower()将布尔值转为true/false字符串因为部分 HTTP 客户端对原生布尔值序列化不一致。返回值解读成功响应示例已简化{ code: 0, msg: 成功, 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 }, request_id: abc123def456 }关键字段说明字段类型说明domainstring查询的域名归一化后suffixstring顶级域如 com、cnregistrarstring域名准备商名称registrar_urlstring准备商官网registrar_abuse_*string准备商滥用投诉邮箱/电话whois_serverstring负责该域名的 Whois 服务器creation_timestring域名创建时间UTC8expiration_timestring域名到期时间UTC8creation_age_textstring人类友好的域龄如“2 年 3 个月”creation_daysint域龄天数valid_daysint距离到期剩余天数domain_statusstring[]域名状态列表含中文解释name_serversstring[]DNS 服务器列表dnssecstringDNSSEC 签名状态unsigned/signedregistrantstring准备人名称可能为空部分 TLD 隐私保护registrant_emailstring准备人邮箱可能为空is_availableboolean域名是否未准备可用于检测可用性is_expiredboolean域名是否已过期expiring_soonboolean是否在 30 天内到期query_timestring查询时间注意registrant和registrant_email字段受 GDPR 等隐私法规影响很多域名不会返回具体信息属于正常现象。常见错误与排查错误码或现象可能原因解决方式HTTP 401 或 403API Key 无效、缺失或未传递X-API-Key头检查密钥是否正确确认已绑定 IP如果有 IP 白名单响应中code非 0域名格式错误、查询频率超限或上游异常检查error字段注意错误响应字段是error而非message源码已修正返回空数据或domain为空输入的域名经自动剥离后为空如仅输入http://确保domain参数是非空的有效域名如example.com请求超时网络问题或上游响应慢设置合理超时建议 10 秒避免长时间阻塞主线程is_available不准确域名刚准备或刚释放缓存可能延迟该接口缓存 24 小时对实时性要求极高的场景需考虑此限制工程化注意事项1. 频率控制接口 QPS 为 5意味着 1 秒内最多发起 5 次请求。若需批量查询如 1000 个域名建议使用time.sleep(0.2)限制请求间隔或采用异步队列控制并发数。import time batch_domains [domain1.com, domain2.com, ...] for d in batch_domains: result query_whois(d, API_KEY) # 处理结果 time.sleep(0.2) # 保证每秒不超过 5 次2. 缓存策略由于上游对同一域名每天只查询一次客户端应避免重复查询同一个域名。可设计本地缓存如 Redis 或文件存储查询结果并设置过期时间 24 小时既节省 API 额度又提高响应速度。3. 参数预处理在调用接口前建议对domain参数进行基本清理def clean_domain(raw: str) - str: 移除 http(s)://、路径、端口、末尾点 raw raw.strip().rstrip(.).lower() if :// in raw: raw raw.split(://)[1] if / in raw: raw raw.split(/)[0] if : in raw: raw raw.split(:)[0] return raw接口本身已有自动归一化但预处理可以减少无效请求。4. 错误重试遇到网络抖动或上游超时建议实现指数退避重试最多 3 次避免因临时故障导致整个任务失败。5. 敏感数据处理响应中的registrant_email等字段可能涉及隐私在日志输出时需脱敏处理避免泄露用户信息。参考文档Whois 域名查询 API 文档原始 Markdown 文档