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/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 | 是 | string | 待查询域名，自动剥离前缀、路径、端口及子域名 | baidu.com |
with_raw | 否 | boolean | 是否返回原始 Whois 文本（约 3KB），仅调试时建议开启 | false |
边界注意：
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 接口原始说明
本文仅作为技术参考，实际使用请以官方最新文档为准。