当前位置：首页 > news >正文

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

news 2026/7/14 10:59:24

适用场景

在日常开发中，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提示。