Domain Analytics Whois API 过滤器说明

本文说明 Domain Analytics Whois API 可用的筛选参数（filters）以及过滤器的写法。

需要注意：

• 过滤器是针对 result 数组中的特定对象定义的，按对应的数据层级填写；
• 你可以通过接口获取当前端点支持的完整过滤字段列表；
• 本接口返回可用过滤器定义，不产生数据查询费用；
• 实支持的过滤字段以接口返回结果为准。

接口说明

请求方式：GET请求地址：

https://api.seermartech.cn/v3/domain_analytics/whois/available_filters

计费说明：调用 参考价：约 ¥0.0000 / 次 说明：扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用后，接口会返回该 API 可用的过滤参数列表。返回数据为 JSON，核心位于 tasks 数组中。

---

响应结构

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，错误码列表参考 /v3/appendix/errors
status_message	string	通用提示信息，参考 /v3/appendix/errors
time	string	请求执行时间，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

tasks 数组字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，参考 /v3/appendix/errors
status_message	string	任务提示信息，参考 /v3/appendix/errors
time	string	任务执行时间，单位秒
cost	float	单个任务费用，单位 USD
result_count	integer	result 数组中的结果数量
path	array	URL 路径
data	object	含 GET 请求 URL 中传的参数
result	array	返回可用于数据过滤的参数列表；这些参数按可使用的端点进行分组

---

过滤器写法

过滤器通过 filters 字段传。

字段名	类型	说明
filters	array	结果过滤条件数组，可选；最多可添加 8 个过滤条件；多个条件之间需使用逻辑运算符 and 或 or 连接

过滤器由以下部分组成：

组成部分	类型	说明
$item_array	string	过滤器中的对象名称，可选；可用值：keyword_data、ranked_serp_element
$results_array	string	过滤器中的结果数组名称，可选；可用值：keyword、keyword_info、check_url、se_results_count、serp_item、metrics
$parameter_field	string	要过滤的字段名；如启用过滤则填；表示上级 $results_array 或 $item_array 中的字段
$filter_operator	string	过滤操作符；如启用过滤则填
$filter_value	num / str / bool / array.str	过滤值；如启用过滤则填

---

支持的过滤操作符

按字段类型支持的操作符如下：

布尔类型 bool

• =
• <>

数值类型 num

• <
• <=
• >
• >=
• =
• <>
• in
• not_in

字符串类型 str

• like
• not_like
• in
• not_in
• =
• <>
• regex
• not_regex

字符串数组 array.str

• has
• has_not

数值数组 array.num

• has
• has_not

时间类型 time

• <
• >

时间使用以下格式：

yyyy-mm-dd hh-mm-ss +00:00

示例：

2021-01-29 15:02:37 +00:00

---

过滤值填写规则

in / not_in

当操作符为 in 或 not_in 时，$filter_value须传数组。

示例：

["value_1", "value_2"]

regex / not_regex

• 适用于字符串字段；
• 正则语法使用 RE2 规则；
• regex 和 not_regex 中可填写的最大字符数为 1000。

like / not_like

使用这两个操作符时，应合 % 通符，才能得到准确结果。

示例含义：

• %seo%：匹 seo 的值
• seo%：匹以 seo 开头的值
• %seo：匹以 seo 结尾的值

例如：

• 返回 domain 字段中 seo 的记录
• 排除 domain 字段中 seo 的记录

---

可用过滤字段

本页对应的是 Domain Analytics Whois Overview 端点的过滤器定义，适用端点路径为：

/v3/domain_analytics/whois/overview/live/

完整可用过滤字段建议直接通过下列接口动态获取：

GET https://api.seermartech.cn/v3/domain_analytics/whois/available_filters

---

请求示例

cURL

curl -X GET "https://api.seermartech.cn/v3/domain_analytics/whois/available_filters" \
 -H "Authorization: Bearer smt_live_YOUR_KEY"

Python

import requests

url = "https://api.seermartech.cn/v3/domain_analytics/whois/available_filters"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY"
}

# 获取 Whois API 可用过滤器列表
response = requests.get(url, headers=headers)
print(response.json)

TypeScript

const url = "https://api.seermartech.cn/v3/domain_analytics/whois/available_filters";

async function main {
 // 获取 Whois API 可用过滤器列表
 const response = await fetch(url, {
 method: "GET",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 },
 });

 const data = await response.json;
 console.log(data);
}

main;

---

响应示例

{
 "version": "0.1.20220819",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0594 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "domain_analytics",
 "function": "available_filters",
 "se": "whois"
 },
 "result": []
 }
 ]
}

说明：result 中会返回该接口当前支持的过滤字段定义。不同版本或不同端点下，字段列表可能有所调整，请以实时响应为准。

---

错误码说明

本接口的通用错误码与任务状态码可参考：

• /v3/appendix/errors

重点字段：

字段	说明
status_code	整体请求状态码
status_message	整体请求状态说明
tasks[].status_code	单个任务状态码
tasks[].status_message	单个任务状态说明

如果 tasks_error 大于 0，说明本次返回中存在失败任务，应检查对应任务的状态码和提示信息。

使用建议

• 在正式构造查询条件前，调用本接口拉取可用过滤字段，传无效参数；
• 编写复杂筛选条件时，确认字段所属层级，确保 $item_array、$results_array、$parameter_field 的路径正确；
• 使用 like / not_like 时务加 %，否则可能无法得到预期结果；
• 使用 regex 时注意 RE2 语法限制，以及 1000 字符的长度上限；
• 若使用 in / not_in，请确保过滤值为数组格式。

实用场景

• 预校验筛选条件：在调用 /v3/domain_analytics/whois/overview/live/ 前获取可用过滤字段，减少无效请求和调试成本。
• 动态生成查询界面：根据接口返回的过滤字段，自动生成后台筛选器页，提升 SEO 工产品的可维护性。
• 约束高级检索逻辑：为域名 Whois 数据分析场景预确定可用字段、类型和操作符，降低复杂查询的出错率。
• 统一过滤器：将平台 API 返回的过滤能力同步到规则引擎，实现不同查询模块的一致筛选体验。
• 支持运营人员自助分析：把可用过滤字段转换为业务可选项，让非技术人员也能组合 Whois 检索条件，快速定位目标域名数据。