AI Keyword Data 可用筛选条件

GET /v3/ai_optimization/ai_keyword_data/available_filters

接口说明

本接口用于获取 AI Keyword Data API 支持的筛选条件（available filters）。返回结果会列出各个端点可用的过滤字段，并按可使用的端点进行分组。

筛选条件与响应中的特定 result 对象，使用时应对应对象的字段结构来构造过滤表达式。

• 请求方式：GET
• 请求地址：https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/available_filters
• 计费说明：调用本接口不收费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

你也可以通过本接口获取完整的可用过滤字段列表，用于动态生成查询构造器、后台筛选面板或校验过滤参数是否合法。

---

返回结构

接口返回 JSON 格式数据，顶层 tasks 数组，每个任务中本次请求的执行结果。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表参考 /v3/appendix/errors
status_message	string	通用状态信息，完整列表参考 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	请求总成本，单位 USD；本接口通常为 0
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	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	当前任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	GET 请求 URL 中传的参数
result	array	结果数组，可用于数据筛选的参数；这些参数会按适用端点分组返回

---

筛选条件结构说明

AI Keyword Data 端点中的 filters 参数为数组类型，用于描述结果过滤条件。

filters 字段定义

字段	类型	说明
filters	array	结果过滤参数数组

过滤表达式规则

filters 的结构由以下部分组成：

1. 过滤字段 filtered_field
2. 操作符 filter_operator
3. 过滤值 filter_value
4. 多个条件之间使用逻辑运算符连接：and / or

使用约束

• 一次最多可添加 8 个过滤条件
• 如果传多个过滤条件，条件之间显式指定逻辑运算符：
• and
• or

字段说明

字段	类型	说明
filtered_field	string	支持筛选的字段名，例如：question、ai_search_volume
filter_operator	string	过滤操作符，支持范围取决于字段类型
filter_value	mixed	过滤值，格式与 filtered_field 的数据类型一致

---

支持的过滤操作符

数值类型字段 num

如果字段类型为数值，可使用以下操作符：

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

字符串类型字段 str

如果字段类型为字符串，可使用以下操作符：

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

特别说明

• 当使用 in 或 not_in 时，filter_value须传数组
• regex 和 not_regex 中可传的字符数上限为 1000

---

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/available_filters" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/available_filters"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

async function getAvailableFilters {
 const response = await axios.get(
 "https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/available_filters",
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 console.log(response.data);
}

getAvailableFilters.catch(console.error);

---

响应示例

以下示例展示了接口的基础返回结构。由于返回会完整的可筛选字段列表， result通常较长。

{
 "version": "0.1.20250526",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0501 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "ai_optimization",
 "function": "available_filters"
 },
 "result": []
 }
 ]
}

---

响应状态码说明

本接口会返回通用状态码以及任务级状态码：

• 顶层 status_code：表示整个请求的总体状态
• tasks[].status_code：表示单个任务的执行状态

常见成功状态：

状态码	说明
20000	请求成功

完整错误码与状态信息请参考：

• /v3/appendix/errors

---

使用建议

建议在以下场景中调用本接口：

1. 在正式查询前读取可用过滤字段，提交不支持的筛选条件
2. 在控制台或中动态渲染筛选器项
3. 在构造复杂检索逻辑时，根据字段类型自动限制可选操作符
4. 在保存用户自定义筛选模板前，校验字段与操作符是否合法

---

筛选条件示意

以下为筛选结构的逻辑示意，并非本接口的请求体：

[
 ["question", "like", "how"],
 "and",
 ["ai_search_volume", ">", 100]
]

说明：

• question 为字符串字段，适合使用 like
• ai_search_volume 为数值字段，适合使用 >
• 多个条件之间用 and 连接

---

注意事项

• 本接口本身返回“哪些字段可以筛选”，不直接返回数据
• 过滤条件与对应业务端点的 result 对象结构一致
• 同一个字段是否可筛选、支持哪些操作符，应以本接口返回结果为准
• 当使用正则筛选时，请控制表达式长度， 1000 字符
• 虽然本接口不收费，但建议仍记录 cost 字段以便统一审计调用成本

实用场景

• 动态生成筛选面板：自动读取 AI Keyword Data 可筛选字段，减少前端硬编码，提升后台灵活性
• 校验用户自定义查询：在保存筛选模板前校验字段名和操作符是否合法，降低请求报错率
• 构建探索：基于可用字段组合搜索量、问题词、语义属性等筛选条件，提升挖掘效率
• 适字段变更：定期拉取最新可用过滤列表，及时发现平台字段调整，降低接口容风险
• 限制无效筛选组合：根据字段类型约束可选操作符，把字符串操作符错误用于数值字段，提高查询准确性