Whois 域名查询 API 的调用限制与用量边界说明

适用场景在日常开发中Whois 信息查询常用于以下场景域名抢注提醒通过定期查询未准备域名is_available: true来判断是否释放。域名过期监控检测expiring_soon字段提前通知续费。域名归属验证确认准备商、准备主体辅助安全分析。域名年龄评估根据creation_age_text判定域龄用于 SEO 或信誉评估。这些场景的共性是需要高频或批量调用 API因此理解其调用限制与用量边界至关重要——否则可能因超限导致请求被拒绝或数据延迟。接口能力概览与调用边界基础能力摘要能力项说明支持的 TLD几乎所有 ICANN 认证后缀.com / .cn / .net / .org / .io / .me / .top / .xyz 等自动归一化自动剥离http(s)://、路径、:port、子域名由上游处理域名可用性检测未准备域名返回is_available: true可用于抢注前查询到期告警30 天内到期返回expiring_soon: true域龄展示creation_age_text返回「N 年 M 月」可读字符串国内 .cn 准备主体中文上游whoiscx对国内域名返回中文准备主体名缓存策略同一域名 24 小时内只调一次上游 Whois 服务器全天数据一致错误响应字段错误字段是error而非message修复了上游原始 BUG调用边界核心QPS 5/sAPI 的查询速率限制为5 次/秒QPS。这意味着在 1 秒窗口内最多只能发送 5 个有效请求。超过此限制的请求将被拒绝返回 HTTP 429Too Many Requests或类似的限流错误。边界提示5 QPS 是接口级限制并非按 IP 或 API Key 独立统计文档未说明是否可提升建议按默认值设计业务。若需更高 QPS建议本地引入域名查询结果缓存如 Redis对同一个域名一天只查一次。请求参数与鉴权接口地址与方式接口GET https://v1.apizero.cn/api/whois请求头X-API-Key: {你的 API Key}Query 参数参数名必填类型说明示例domain是string待查询域名自动剥离前缀、路径、端口及子域名baidu.comwith_raw否boolean是否返回原始 Whois 文本约 3KB仅调试时建议开启false边界注意domain参数即使传入https://www.example.com/path?q1最终也只查询example.com。但若传入的是 IP 地址或不合法域名如abc则会返回错误错误字段error。with_rawtrue会显著增加响应体大小且消耗上游资源——频繁使用可能触发额外限流未文档化建议避免。请求示例可复制的 curl以下示例使用环境变量$APIZERO_API_KEY传递 API Keycurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/whois?domainapizero.cn若需查看原始 Whois 文本追加with_rawtruecurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/whois?domainapizero.cnwith_rawtrue注意请提前申请并替换 API Key。示例中的域名apizero.cn可换为任何你关注的域名。响应结构与字段解读成功响应为 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, registrant: , registrant_email: , creation_time: 1999-10-11 19:05:17, expiration_time: 2028-10-11 19:05:17, creation_days: 9704, creation_age_text: 26 年 7 个月, valid_days: 888, domain_status: [ clientDeleteProhibited 注册商设置禁止删除, clientTransferProhibited 注册商设置禁止转移 ], name_servers: [ NS1.BAIDU.COM, NS2.BAIDU.COM, NS3.BAIDU.COM ], dnssec: unsigned, whois_server: whois.markmonitor.com, is_available: false, is_expired: false, expiring_soon: false, query_time: 2026-05-07 09:18:54 } }关键字段解释is_available若为true表示域名未准备可抢注。此时registrar、creation_time等字段可能为空。expiring_soon剩余有效期 ≤ 30 天时为true。creation_age_text人类可读的域龄如26 年 7 个月。query_time实际查询的时间戳与服务器时间一致若缓存命中此时间依然是当前时间但背后数据是 24h 内的缓存。调用限制与用量边界细节1. 速率限制QPS阈值5 次/秒超过后 HTTP 状态码通常为429。重置以秒为滑动窗口不支持突发burst。建议客户端应做本地排队如使用令牌桶算法每秒 5 个令牌避免瞬间请求堆积。2. 缓存策略与数据新鲜度同一域名在24 小时内只调用一次上游 Whois 服务器后续查询均直接返回缓存数据。这意味着当天内第二次查询同一个域名响应中的query_time虽然刷新但底层creation_time、expiration_time等字段与第一次完全一致。3. 错误响应字段特殊说明官方文档指出上游返回的错误字段为error而非message这是之前源码的 BUG 修复结果。因此客户端错误处理应解析error字段{ code: 1001, error: domain parameter is missing or invalid, request_id: xxx }常见错误码code1001参数错误如domain为空或格式不合法。code2001API Key 无效或缺失。code3001上游 Whois 服务器响应超时或失败。code4001调用频率超限QPS 超出。4. 自动归一化边界子域名如www.baidu.com会被上游处理为baidu.com后查询不会返回子域名的独立 Whois 信息。查询.cn域名时若准备主体在国内registrant字段会返回中文名称如“极数本源福州科技有限公司”而非英文拼写——这是上游whoiscx的特性。若传入的字符串无法解析为合法域名如abc、123或 IP则返回error提示。工程化注意事项1. 本地缓存策略由于 API 已存在 24h 缓存客户端无需再对同一域名做二次缓存但为了减少请求数并避免 QPS 超限建议建立一个待查询域名队列以5 个/秒速率消费。将is_available状态和expiring_soon信息写入本地数据库如 Redis 24h 过期同一域名在一天内不再请求 API。2. 错误重试准则对于 HTTP 429 或code4001应等待至少 1 秒后重试最大重试次数 3 次且需采用指数退避1s、2s、4s。对于code3001上游失败可间隔 30 秒后重试因为这是临时性故障。对于code1001参数错误应检查代码逻辑不重试。3. 批量查询优化假如需要监控 1000 个域名一天内无法全部完成因为 QPS 5/s一天最多 5×86400 432,000 次理论上够用但实际业务往往在短时间内集中查询。推荐做法将查询分散到全天如每小时查询 200 个域名均匀分布。利用with_rawfalse尽量减少响应大小降低带宽消耗对限流无直接影响但可减少资源占用。4. API Key 安全绝对不要将 API Key 硬编码在客户端代码或版本控制中。使用环境变量或密钥管理服务。5. 时区与时间字段处理返回的时间字段creation_time、expiration_time均为 UTC 时间示例中为1999-10-11 19:05:17实际未标注时区但推测为 UTC。建议在显示时转换为当地时区并注意与query_time的关系。参考文档官方文档Whois 域名查询 API 文档原始 MarkdownWhois 接口原始说明本文仅作为技术参考实际使用请以官方最新文档为准。