Content Analysis API 过滤器

GET /v3/content_analysis/available_filters

本接口使用 GET 方法，路径为：

GET https://api.seermartech.cn/v3/content_analysis/available_filters

本接口用于获取 Content Analysis API 可用的过滤字段、过滤运算符及适用端点。过滤器针对响应中 result 数组的对象。

计费说明

调用本接口不收取费用，响应中的 cost 通常为 0。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求方式

请求头

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求示例

curl

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

TypeScript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/content_analysis/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);
  });

Python

import requests

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

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

if response.ok:
    # 处理过滤器列表
    print(response.json())
else:
    print(f"HTTP 错误：{response.status_code}，响应：{response.text}")

响应结构

接口返回 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 格式
tasks[].status_code	integer	任务状态码，通常在 10000 至 60000 范围
tasks[].status_message	string	任务提示信息
tasks[].time	string	任务执行耗时，单位为秒
tasks[].cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks[].result_count	integer	result 数组中的数量
tasks[].path	array	请求 URL 路径
tasks[].data	object	GET 请求 URL 中传递的参数
tasks[].result	array	可用过滤器及说明

tasks[].result 中可用于数据过滤的完整参数列表。参数会适用的 API 端点进行分组。

过滤器结构

过滤器通过 filters 字段传递，通常位于任务请求体的对象中。

字段名	类型	说明
filters	array	过滤条件数组
filtered_field	string	支持过滤的字段
filter_operator	string	过滤运算符
filter_value	object	过滤值，格式与 filtered_field 的字段类型匹

基本格式

单个过滤条件通常采用以下结构：

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

例如：

{
  "filters": [
    ["domain_rank", ">", 500]
  ]
}

多个过滤条件

一次最多可添加 8 个过滤条件。当多个条件时，在条件之间指定逻辑运算符 and 或 or。

示例：

{
  "filters": [
    ["domain_rank", ">", 500],
    "and",
    ["content_info.title", "like", "%seo%"]
  ]
}

也可以使用 or：

{
  "filters": [
    ["domain_rank", ">=", 700],
    "or",
    ["content_info.sentiment_connotations.fun", "=", 1]
  ]
}

filtered_field

filtered_field 用于指定需要过滤的字段。部分字段采用嵌套路径格式，例如：

content_info.$parameter_field
content_info.$results_array.$parameter_field

字段示例：

domain_rank
content_info.title
content_info.sentiment_connotations.fun

可用字段及适用端点，请以本接口返回的完整列表为准。

filter_operator

过滤运算符与字段类型匹。

字段类型	可用运算符
num	<、<=、>、>=、=、<>、in、not_in
str	like、not_like、=、<>、regex、not_regex、in、not_in、match、not_match
array.str	has、has_not
array.num	has、has_not
time	<、>

in 和 not_in

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

示例：

{
  "filters": [
    ["domain_rank", "in", [100, 200, 300]]
  ]
}

{
  "filters": [
    ["content_info.title", "not_in", ["示例标题", "测试标题"]]
  ]
}

时间字段

时间值使用以下格式：

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

示例：

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

对应的过滤条件示例：

{
  "filters": [
    ["last_updated", ">", "2021-01-29 15:02:37 +00:00"]
  ]
}

正则表达式限制

regex 和 not_regex 运算符中的正则表达式，最大长度为 1000 个字符。

filter_value

filter_value 是用于比较的过滤值数据类型和格式与 filtered_field 相匹。

常见示例：

{
  "filters": [
    ["domain_rank", ">=", 500]
  ]
}

{
  "filters": [
    ["content_info.title", "like", "%marketing%"]
  ]
}

{
  "filters": [
    ["content_info.sentiment_connotations.fun", "=", 1]
  ]
}

响应示例

{
  "version": "0.1.20220819",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0553 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0553 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "content_analysis",
        "available_filters"
      ],
      "data": {
        "api": "content_analysis",
        "function": "available_filters"
      },
      "result": [
        {
          "endpoint": "content_analysis/summary",
          "filters": [
            {
              "filtered_field": "domain_rank",
              "type": "num",
              "operators": [
                "<",
                "<=",
                ">",
                ">=",
                "=",
                "<>",
                "in",
                "not_in"
              ]
            }
          ]
        }
      ]
    }
  ]
}

错误处理

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

-局请求：检查顶层 status_code

• 单个任务：检查 tasks[].status_code
• 成功状态通常为 20000
• 发生错误时，结合 status_message 获取原因

完整错误码和状态信息请参考本平台错误码文档。

实用场景

• 获取可用过滤字段：在构建分析筛选功能前动态读取字段和运算符，因字段变更导致查询请求失败。
• 筛选高质量来源：使用 domain_rank、页面标题或指标过滤结果，快速定位高权威网站和页面。
• 分析特定绪：通过 content_info.sentiment_connotations.* 等嵌套字段筛选特定绪倾向的，品牌舆分析。
• 组合复杂条件：使用 and、or 组合多个字段条件，构建面向行业、主题、质量区间的精细化分析报表。
• 按时间筛选数据：使用时间字段和时间运算符过滤指定时间范围的，支持趋势监测和定期 SEO 数据对比。