域名交易市场 API 参数详解与接入最佳实践
适用场景
域名交易市场为站长、域名投资人及行业研究人员提供从 EDNS 公开交易数据中获取域名列表、用量说明、交易类型等信息的便捷途径。常见场景包括：
- 扫货短米：通过
max_length和max_price筛选出用量说明合理、长度较短的域名，用于建站或转售。 - 行业研究：按后缀（如
.com、.cn）和交易类型（一口价、竞拍）统计市场成交活跃度。 - 行情监测：定期轮询接口，结合
sale_type与price构建用量说明趋势预警。
接口能力边界
- 接口限速QPS 5，即每秒最多请求 5 次，超出将返回 429 Too Many Requests。
- 每次最多返回 100 条记录（
pagesize ≤ 100），总页数由服务端动态计算。 - 支持的筛选维度包括用量说明上限、域名长度上限、后缀和交易类型，均为可选参数。
- 数据为公开的 EDNS 域名交易市场快照，不承诺实时性，部分最近成交记录可能存在延迟。
鉴权方式
所有请求必须在 HTTP 头部携带X-API-Key，值为从控制台获取的 API 密钥。示例：
X-API-Key: your_actual_api_key密钥需妥善保管，不要硬编码在公开代码仓库中。推荐使用环境变量注入。
参数详解
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| page | number | 否 | 1 | 页码，从 1 开始 |
| pagesize | number | 否 | 50 | 每页条数，最大值 100 |
| max_price | number | 否 | 无 | 筛选用量说明≤该值的域名（单位：元） |
| max_length | number | 否 | 无 | 筛选域名长度≤该值（不含后缀） |
| suffix | string | 否 | 无 | 指定后缀，如.com、.net |
| sale_type | string | 否 | 无 | 交易类型，如一口价、竞拍 |
注意：参数值不应包含特殊符号，suffix 带点号。若传入不存在的交易类型，接口仍会返回结果但可能为空。
可复制的 curl 请求示例
以下示例演示获取第 2 页、每页 30 条、用量说明不超过 1000、后缀为.com的一口价域名：
# 替换 YOUR_API_KEY 为真实密钥 curl -sS \ -X GET \ -H "X-API-Key: YOUR_API_KEY" \ "https://v1.apizero.cn/api/domain-trade?page=2&pagesize=30&max_price=10000&suffix=.com&sale_type=一口价"返回体示例（JSON）：
{ "code": 0, "data": { "count": 30, "current_page": 2, "list": [ { "name": "short.io", "price": "3200", "sale_type": "一口价" }, { "name": "mybox.com", "price": "8900", "sale_type": "一口价" } ], "total_pages": 50 }, "msg": "成功" }返回值解读
顶层字段说明：
code：业务状态码，0表示成功，非0表示错误。msg：描述信息，成功时通常为“成功”。data：分页数据对象，包含count（当前页实际条数）、current_page（当前页码）、list（域名列表）、total_pages（总页数）。
list中每项字段：
| 字段名 | 类型 | 说明 |
|---|---|---|
| name | string | 域名全名（含后缀） |
| price | string | 用量说明，单位为元（字符串） |
| sale_type | string | 交易类型：一口价 / 竞拍等 |
注意price使用字符串而非数值，因为部分用量说明可能包含小数或较长数字，前端展示或比较时需转为数值。
常见错误处理
| HTTP 状态码 | 可能原因 | 解决方式 |
|---|---|---|
| 401 Unauthorized | API Key 缺失或无效 | 检查X-API-Key是否正确设置 |
| 429 Too Many Requests | 超过 QPS 限制 | 降低请求频率，加入退避策略 |
| 400 Bad Request | 参数非法（如 pagesize > 100） | 校验参数范围 |
| 500 Internal Server Error | 服务端异常 | 等待后重试，若持续发生请联系技术支持 |
业务错误（返回code != 0）：
code=1001：参数格式错误（如 page 为负数）。code=1002：后缀格式不正确（缺少点号等）。code=1003：交易类型不在允许列表中（以文档为准）。
工程化注意事项
- 并发控制：QPS 5 意味着不推荐使用单进程同步循环请求。若需采集多页数据，应使用令牌桶或信号量限制并发，例如每秒只发起 5 个请求。
- 分页遍历策略：获取
total_pages后，逐页请求，但应合理设置pagesize以减少请求次数。推荐 pagesize=100。 - 重试与容错：对 429 和 5xx 实现指数退避重试（如初始等待 1 秒，最多 3 次）。
- 数据存储：用量说明字段建议以分或毫为单位存储整型，避免浮点误差。若保留字符串，比较时需转换为 float 或 Decimal。
- 缓存：域名交易数据变动不频繁，可为相同查询条件设置短时缓存（如 60 秒），降低接口调用次数。
- 安全：API Key 不要泄露在客户端代码中。服务端调用时使用环境变量或在配置中心管理。
代码接入示例（Python）
import requests import os API_KEY = os.environ.get("APIZERO_API_KEY") BASE_URL = "https://v1.apizero.cn/api/domain-trade" params = { "page": 1, "pagesize": 50, "max_price": 5000, "suffix": ".com" } headers = {"X-API-Key": API_KEY} resp = requests.get(BASE_URL, params=params, headers=headers) if resp.status_code == 200: data = resp.json() if data["code"] == 0: for domain in data["data"]["list"]: print(f"{domain['name']}: {domain['price']} 元 ({domain['sale_type']})") else: print("业务错误:", data["msg"]) else: print("HTTP 错误:", resp.status_code)参考文档
- 官方 API 文档：https://apizero.cn/aidocs/domain-trade
- 原始 Markdown 文档：https://apizero.cn/aidocs/domain-trade/raw.md
（注：如文档版本更新，请以最新版本为准。）