本平台 Labs API 筛选器

本文介绍 本平台 Labs API 端点支持的筛选器结构、字段类型、运算符及使用示例。

接口契约：

• 方法： GET
• 路径： /v3/dataforseo_labs/available_filters
• 完整 URL： https://api.seermartech.cn/v3/dataforseo_labs/available_filters

筛选器与响应 result 数组中的特定对象，根据目标对象所在的层级指定筛选路径。

> 注意：order_by 不支持将以下字段类型作为排序规则：array.str、array.num。

计费说明

调用本接口不会产生费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

获取可用筛选器列表

调用以下接口可获取 本平台 Labs API 支持的完整筛选器列表：

GET https://api.seermartech.cn/v3/dataforseo_labs/available_filters
Authorization: Bearer smt_live_YOUR_KEY

cURL 示例

curl --request GET \
  --url https://api.seermartech.cn/v3/dataforseo_labs/available_filters \
  --header 'Authorization: Bearer smt_live_YOUR_KEY'

Python 示例

import requests

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

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

print(response.json())

TypeScript 示例

const response = await fetch(
  "https://api.seermartech.cn/v3/dataforseo_labs/available_filters",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
    },
  },
);

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

响应结构

接口返回 JSON 对象 tasks 数组本次请求的任务信息，result 数组可用于数据筛选的完整参数列表。筛选参数会可使用的 API 端点进行分组。

顶层字段

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

任务字段

字段名	类型	说明
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	请求 URL 路径
data	object	GET 请求 URL 中传的参数
result	array	可用筛选参数列表

响应示例

{
  "version": "0.1.20251117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0537 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0100 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "available_filters"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "available_filters"
      },
      "result": [
        {
          "endpoint": "example_endpoint",
          "filters": []
        }
      ]
    }
  ]
}

筛选器结构

在调用 本平台 Labs API 端点时，可通过 filters 参数指定结果筛选条件。

基本格式

{
  "filters": [
    [
      "$results_array.$parameter_field",
      "$filter_operator",
      "$filter_value"
    ]
  ]
}

多个条件最多可同时指定 8 个筛选器，条件之间使用逻辑运算符 and 或 or：

{
  "filters": [
    [
      "keyword_data.keyword_info.search_volume",
      ">",
      1000
    ],
    "and",
    [
      "keyword_data.keyword",
      "like",
      "%seo%"
    ]
  ]
}

筛选路径中使用 . 和 , 作为分隔符，路径以目标端点支持的字段为准。

部分端点支持另一种筛选结构：

• Page Intersection
• Ranked Keywords
• Subdomains
• Relevant Pages
• Competitors Domain
• Categories For Domain
• Domain Intersection

使用替代结构时，需要在条件右侧的字段前添加 $item->。条件左侧和右侧的 $parameter_field须相同的数据类型，例如 bool、num、str 或 time。

筛选器字段

字段名	类型	说明
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	number、string、boolean、time	筛选值。应用筛选器时为填项

支持的筛选运算符

字段类型	支持的运算符
bool	=、<>
num	<、<=、>、>=、=、<>、in、not_in
str	match、not_match、like、not_like、ilike、not_ilike、in、not_in、=、<>、regex、not_regex
array.str	has、has_not
array.num	has、has_not
time	<、>

in 和 not_in

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

{
  "filters": [
    [
      "keyword_data.keyword",
      "in",
      ["seo", "marketing", "analytics"]
    ]
  ]
}

时间字段

time 类型使用以下格式：

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

示例：

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

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

regex 和 not_regex

regex 和 not_regex 可与字符串值合使用，并遵循 RE2 正则表达式语法。

• 正则表达式最大长度为 1000 个字符
• regex：匹符合表达式的字符串
• not_regex：排除符合表达式的字符串

示例：

{
  "filters": [
    [
      "keyword_data.keyword",
      "regex",
      "^(seo|marketing)"
    ]
  ]
}

like 和 not_like

使用 like 和 not_like 时，建议在匹前后添加 % 通符，以获得准确结果。

返回 keyword 字段中 seo 的项目：

{
  "filters": [
    [
      "keyword_data.keyword",
      "like",
      "%seo%"
    ]
  ]
}

排除 keyword 字段中 seo 的项目：

{
  "filters": [
    [
      "keyword_data.keyword",
      "not_like",
      "%seo%"
    ]
  ]
}

match 和 not_match

match 和 not_match 是用于字符串值的搜索运算符。

返回不完整单词 camera 的：

{
  "filters": [
    [
      "keyword_data.keyword",
      "not_match",
      "camera"
    ]
  ]
}

返回完整单词 phone 的：

{
  "filters": [
    [
      "keyword_data.keyword",
      "match",
      "phone"
    ]
  ]
}

筛选器使用注意事项

1. filters须作用于对应端点 result 数组中的字段。
2. $parameter_field须与字段的数据类型匹。
3. 多个筛选条件之间使用 and 或 or 连接。
4. 单次请求最多支持 8 个筛选条件。
5. array.str 和 array.num 字段可以使用 has 或 has_not，但不能用于 order_by 排序。
6. 使用 in 或 not_in 时，筛选值是数组。
7. 使用 regex 或 not_regex 时，表达式长度不能 1000 个字符。
8. 不同端点支持的字段和筛选路径可能不同，应通过本接口获取完整可用列表。

实用场景

• 筛选高搜索量：使用数值条件过滤搜索量高于指定阈值的，优制定和投放策略。
• 定位目标词的：使用 like、match 或正则表达式筛选品牌词、产品词或主题词的。
• 排除无：使用 not_like、not_match 或 not_in 去除竞品词、低词和不适合业务的搜索词。
• 筛选特定时间范围的数据：使用 time 类型条件获取指定更新时间之后的、排名或指标数据。
• 组合分析与 SERP 数据：通过多个筛选器结合搜索量、排名、SERP 数量和指标字段，缩小 SEO 竞品分析范围。