<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# Whois 域名查询

> 对接 whoiscx.com 上游，查询域名注册信息（注册商 / 注册主体 / 创建时间 / 到期时间 / DNS 服务器 / 域名状态 / DNSSEC 等）。

• **支持所有主流 TLD**：.com / .cn / .net / .org / .io / .me / .top / .xyz 等几乎所有 ICANN 认证后缀
• **自动归一化**：传入 `https://www.baidu.com/abc` 会自动剥离为 `baidu.com`
• **域名可用性检测**：未注册域名返回 is_available=true，可用于域名抢注前查询
• **到期告警**：30 天内到期返回 expiring_soon=true，便于前端高亮提示
• **域龄展示**：creation_age_text 返回「N 年 M 月」人类可读字符串
• **国内 .cn 主体中文**：whoiscx 上游对国内域名返回中文注册主体名（如「极数本源（福州）科技有限公司」）
• **缓存 24h**：whois 数据年级变化，全天同一域名查询只调 1 次上游
• **修复源码 BUG**：错误响应字段是 `error` 不是 `message`，源码取错丢失了上游真实错误

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `whois` |
| 接口名称 | Whois 域名查询 |
| 接口地址 | `https://v1.apizero.cn/api/whois` |
| 请求方法 | `GET` |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 100 次（已认证用户） |
| 匿名每日额度 | 30 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 30 次、QPS 2；登录用户每日 100 次、QPS 5（全部免费）。命中 24h 缓存不计入上游配额。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `domain` | `string` | 是 | 待查询域名。自动剥离 http(s):// 前缀、路径、:port 后缀、子域名（如 www.baidu.com → baidu.com 由上游处理） | `baidu.com` |
| `with_raw` | `bool` | 否 | 是否返回 raw_whois 原始 whois 文本（约 3KB），默认 false。建议仅调试时启用 | `false` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/whois?domain=baidu.com&with_raw=false&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `domain` | `string` | 归一化后的主域名（如 baidu.com） | — |
| `suffix` | `string` | 域名后缀（如 com / cn / org） | — |
| `is_available` | `boolean` | 域名是否可注册（true=未注册可抢注，false=已被注册） | — |
| `is_expired` | `boolean` | 域名是否已过期 | — |
| `expiring_soon` | `boolean` | 30 天内即将到期（true 时建议提示用户续费） | — |
| `registrar` | `string` | 注册商名称（如 阿里云 / GoDaddy / MarkMonitor） | — |
| `registrant` | `string` | 注册主体（个人/公司名，受隐私保护可能为空） | — |
| `registrant_email` | `string` | 注册联系邮箱（多数被脱敏） | — |
| `creation_time` | `string` | 注册时间（YYYY-MM-DD HH:MM:SS） | — |
| `expiration_time` | `string` | 到期时间（YYYY-MM-DD HH:MM:SS） | — |
| `creation_days` | `number` | 已注册天数（域龄） | — |
| `creation_age_text` | `string` | 域龄人类可读字符串（如 "28 年" / "3 个月"） | — |
| `valid_days` | `number` | 剩余有效天数 | — |
| `domain_status` | `array` | 域名状态数组（如 clientTransferProhibited） | — |
| `name_servers` | `array` | DNS 服务器数组（如 ["NS1.GOOGLE.COM","NS2.GOOGLE.COM"]） | — |
| `whois_server` | `string` | 权威 whois 服务器（如 whois.markmonitor.com） | — |
| `dnssec` | `string` | DNSSEC 状态（unsigned / signedDelegation） | — |
| `registrar_url` | `string` | 注册商官网 URL | — |
| `registrar_abuse_email` | `string` | 注册商滥用举报邮箱 | — |
| `registrar_abuse_phone` | `string` | 注册商滥用举报电话 | — |
| `query_time` | `string` | 上游查询时间戳 | — |
| `raw_whois` | `string` | 原始 whois 文本（仅在 with_raw=true 时返回） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "domain": "baidu.com",
        "suffix": "com",
        "is_available": false,
        "is_expired": false,
        "expiring_soon": false,
        "registrar": "MarkMonitor Information Technology (Shanghai) Co., Ltd.",
        "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"
        ],
        "whois_server": "whois.markmonitor.com",
        "dnssec": "unsigned",
        "registrar_url": "http:\/\/markmonitor.com",
        "registrar_abuse_email": "abusecomplaints@markmonitor.com",
        "registrar_abuse_phone": "+1.2083895740",
        "query_time": "2026-05-07 09:18:54"
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：domain 为空 / 格式不合法 / 上游报「域名不合法」 |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 上游响应格式异常 / Whois 服务暂不可用 |

## 9. 变更日志

- **1.0.0** (2026-05-07)
  - 首次上线，对接 whoiscx.com whois 查询
  - 修复源码 BUG：错误响应字段实际是 `error` 不是 `message`，源码取错导致永远显示默认错误吞掉上游真实错误信息
  - 新增 expiring_soon 字段（30 天内到期），便于前端高亮提示
  - 新增 creation_age_text 字段（如 "28 年 6 个月"），UX 友好
  - 新增 with_raw 参数控制是否返回 3KB 原始 whois 文本（默认不返回节省传输）
  - 错误细分：上游「域名不合法」映射为 4000 客户端错误，与上游故障 5xx 区分
  - Redis 24h 缓存（whois 数据年级变化，缓存命中提速 90%+）
  - 域名格式校验加强：长度 ≤ 253、剥离 :port 后缀
  - is_available / is_expired / expiring_soon 改为 boolean 类型（源码用 0/1 整数）

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/whois`

Source: `https://apizero.cn/aidocs/whois/raw.md`
Last updated: 2026-05-11T16:16:07+08:00