AI 数据 API：可用过滤器

GET /v3/ai_optimization/ai_keyword_data/available_filters

本接口用于获取 AI 数据 API 支持的过滤器。请求方法与路径为：

GET /v3/ai_optimization/ai_keyword_data/available_filters

过滤器与响应 result 数组中的对象，根据目标端点及字段结构正确指定。调用本接口不会产生费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求地址

https://api.seermartech.cn/v3/ai_optimization/ai_keyword_data/available_filters

本接口无需请求体，也不需要使用 POST 请求。

认证方式

请求头中使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求示例

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)

if response.status_code == 200:
    result = response.json()
    print(result)
else:
    print(f"HTTP 错误：{response.status_code}")
    print(response.text)

TypeScript

import axios from "axios";

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",
      },
    }
  )
  .then((response) => {
    // 处理接口返回数据
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应结构

接口返回 JSON 数据 tasks 数组本次请求的任务信息。

字段	类型	说明
version	string	当前 API 版本
status_code	integer	局状态码
status_message	string	局状态信息
time	string	请求执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务对象数组

tasks 对象字段

字段	类型	说明
id	string	任务唯一标识，采用 UUID 格式
status_code	integer	任务状态码，通常位于 10000 至 60000 范围
status_message	string	任务状态信息
time	string	任务执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	GET 请求中使用的接口参数
result	array	可用过滤器列表，按可使用的 API 端点进行分组

data 对象示例

{
  "api": "ai_optimization",
  "function": "available_filters"
}

响应示例

由于 result 会完整的过滤器定义，返回可能较长。响应结构示例如下：

{
  "version": "0.1.20250526",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0501 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0500 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "ai_keyword_data",
        "available_filters"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "available_filters"
      },
      "result": [
        {
          "filters": []
        }
      ]
    }
  ]
}

完整的 result会列出各个端点支持的过滤字段、操作符和字段类型。

过滤器结构

filters

字段	类型	说明
filters	array	过滤条件数组

过滤条件用于限制接口返回的数据。一次请求最多可添加 8 个过滤条件。

当请求中多个过滤条件时，在条件之间指定逻辑运算符 and 或 or。

过滤器通常由以下三部分组成：

[
  ["filtered_field", "filter_operator", "filter_value"],
  "and",
  ["filtered_field", "filter_operator", "filter_value"]
]

例如：

[
  ["question", "like", "%seo%"],
  "and",
  ["ai_search_volume", ">=", 100]
]

filtered_field

字段	类型	说明
filtered_field	string	支持过滤的字段名称

示例：

question
ai_search_volume

可使用的字段取决于 API 端点。应以本接口返回的过滤器列表为准。

filter_operator

字段	类型	说明
filter_operator	string	过滤操作符

支持的操作符如下：

数值类型字段

适用于 num 类型字段：

<
<=
>
>=
=
<>
in
not_in

示例：

["ai_search_volume", ">=", 100]

字符串类型字段

适用于 str 类型字段：

like
not_like
=
<>
regex
not_regex
in
not_in
match
not_match

示例：

["question", "like", "%seo%"]

使用 in 或 not_in 时，filter_value须传数组：

["question", "in", ["seo", "keyword", "ranking"]]

regex 和 not_regex 操作符中的正则表达式长度最多为 1000 个字符。

filter_value

字段	类型	说明
filter_value	object	过滤值

filter_value 的数据格式与 filtered_field 对应字段的类型一致。例如：

["ai_search_volume", ">", 100]

过滤值 100 为数值。

["question", "=", "what is seo"]

过滤值为字符串。

["question", "in", ["seo", "keyword"]]

过滤值为字符串数组。

错误处理

请根据以下字段判断请求是否成功：

-局请求：status_code

• 单个任务：tasks[].status_code
• 详细信息：status_message 或 tasks[].status_message

当状态码为 20000 时，通常表示请求成功。状态码表示请求或任务处理异常，错误信息以响应中的状态消息为准。

实用场景

• 获取端点支持的过滤字段：在构建 AI 数据查询条件前，确认各端点可用的字段和操作符，因字段不容导致任务失败。
• 筛选高价值：使用 ai_search_volume 等数值字段过滤搜索量较高的，优识别流量潜力的 SEO 主题。
• 匹特定问题：通过 question 字段合 like、regex 或 match，提取与产品、行业或用户意图的问题型。
• 组合多个业务条件：使用 and、or 组合文本、搜索量等条件，构建更精确的选题和分析规则。
• 生成自动化过滤：定期读取可用过滤器列表并同步到 SEO 工，确保筛选逻辑与当前 API 能力保持一致。