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

适用场景

在日常开发中，Whois 信息查询常用于以下场景：

1. 域名抢注提醒：通过定期查询未准备域名（is_available: true）来判断是否释放。
2. 域名过期监控：检测expiring_soon字段，提前通知续费。
3. 域名归属验证：确认准备商、准备主体，辅助安全分析。
4. 域名年龄评估：根据creation_age_text判定域龄，用于 SEO 或信誉评估。

这些场景的共性是需要高频或批量调用 API，因此理解其调用限制与用量边界至关重要——否则可能因超限导致请求被拒绝或数据延迟。

接口能力概览与调用边界

基础能力摘要

调用边界核心：QPS 5/s

API 的查询速率限制为5 次/秒（QPS）。这意味着在 1 秒窗口内最多只能发送 5 个有效请求。超过此限制的请求将被拒绝，返回 HTTP 429（Too Many Requests）或类似的限流错误。

边界提示：

• 5 QPS 是接口级限制，并非按 IP 或 API Key 独立统计？文档未说明是否可提升，建议按默认值设计业务。
• 若需更高 QPS，建议本地引入域名查询结果缓存（如 Redis），对同一个域名一天只查一次。

请求参数与鉴权

接口地址与方式

• 接口：GET https://v1.apizero.cn/api/whois
• 请求头：X-API-Key: {你的 API Key}

Query 参数

边界注意：

• domain参数即使传入https://www.example.com/path?q=1，最终也只查询example.com。但若传入的是 IP 地址或不合法域名（如abc），则会返回错误（错误字段error）。
• with_raw=true会显著增加响应体大小，且消耗上游资源——频繁使用可能触发额外限流（未文档化，建议避免）。

请求示例：可复制的 curl

以下示例使用环境变量$APIZERO_API_KEY传递 API Key：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/whois?domain=apizero.cn"

若需查看原始 Whois 文本，追加&with_raw=true：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/whois?domain=apizero.cn&with_raw=true"

注意：请提前申请并替换 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": "abusecomplaints@markmonitor.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" }

常见错误码：

• code=1001：参数错误（如domain为空或格式不合法）。
• code=2001：API Key 无效或缺失。
• code=3001：上游 Whois 服务器响应超时或失败。
• code=4001：调用频率超限（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 或code=4001，应等待至少 1 秒后重试，最大重试次数 3 次，且需采用指数退避（1s、2s、4s）。
• 对于code=3001（上游失败），可间隔 30 秒后重试，因为这是临时性故障。
• 对于code=1001（参数错误），应检查代码逻辑，不重试。

3. 批量查询优化

假如需要监控 1000 个域名，一天内无法全部完成（因为 QPS 5/s，一天最多 5×86400 = 432,000 次，理论上够用，但实际业务往往在短时间内集中查询）。

推荐做法：

• 将查询分散到全天，如每小时查询 200 个域名，均匀分布。
• 利用with_raw=false尽量减少响应大小，降低带宽消耗（对限流无直接影响，但可减少资源占用）。

4. API Key 安全

• 绝对不要将 API Key 硬编码在客户端代码或版本控制中。使用环境变量或密钥管理服务。

5. 时区与时间字段处理

返回的时间字段（creation_time、expiration_time）均为 UTC 时间（示例中为1999-10-11 19:05:17，实际未标注时区，但推测为 UTC）。建议在显示时转换为当地时区，并注意与query_time的关系。

参考文档

• 官方文档：Whois 域名查询 API 文档
• 原始 Markdown：Whois 接口原始说明

本文仅作为技术参考，实际使用请以官方最新文档为准。