本平台 Labs 可用过滤器

本文档说明如何获取并使用 /v3/dataforseo_labs/ 接口支持的过滤器（filters）参数过滤结构、可用操作符、字段类型限制及响应格式。

接口说明

该接口用于返回 本平台 Labs API 各端点可用的完整过滤字段列表。过滤器与响应 result 数组中的特定对象，因此在构造 filters 时，对应对象层级正确指定字段。

接口路径

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

计费说明

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

过滤器使用说明

在使用 /v3/dataforseo_labs/ 下的任务型接口时，可通过 filters 对结果进行筛选。

基本规则

• filters 是一个数组
• 最多支持同时传 8 个过滤条件
• 多个条件之间需要使用逻辑运算符：
• and
• or
• 过滤器是针对 result 中某个对象字段定义的，字段路径与该端点返回结构一致
• 不能将 array.str、array.num 类型字段用于 order_by 排序

过滤结构

filters 采用数组结构，使用 . 和 , 表示字段层级与条件组织。

部分端点支持另一种替代结构，适用于以下接口：

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

使用替代结构时，条件右侧需要附加 $item->。

同时需要注意：

• 条件左侧与右侧的 $parameter_field 类型一致
• 支持的类型：
• bool
• num
• str
• time

字段说明

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 / 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

• <
• >

时间类型使用以下格式：

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

示例：

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

操作符使用要点

in / not_in

当使用 in 或 not_in 时，$filter_value须是数组。

regex / not_regex

• 适用于字符串值
• 使用 RE2 正则语法
• regex 和 not_regex 中可传的字符数上限为 1000

like / not_like

为了获得准确结果，需在匹模式中 % 通符。

示例含义：

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

match / not_match

这是检索操作符，适用于字符串类型。

示例含义：

• 返回不 camera 的
• 返回 phone 的

获取可用过滤字段

你可以通过以下接口获取完整的可用过滤字段列表。

请求示例

cURL

curl -X GET "https://api.seermartech.cn/v3/dataforseo_labs/available_filters" \
 -H "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)
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 数组中。

字段名	类型	说明
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	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	返回结果数组，各端点支持的过滤参数，按端点分组

响应示例

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

注意事项

• 过滤器与目标接口返回的对象结构对应
• 构造复杂过滤条件时，建议调用 /v3/dataforseo_labs/available_filters 获取该端点支持的字段
• array.str 和 array.num 类型字段支持过滤，但不支持作为 order_by 的排序依据
• 若使用正则过滤，请控制表达式长度， 1000 字符限制

实用场景

• 筛选高价值：按搜索量、竞争度、难度等字段过滤结果，快速锁定更值得投放或优化的词。
• 定位低竞争机会词：组合 and / or 条件筛选“有流量但竞争较低”的，提升获客效率。
• 洗批量分析结果：在域名、页面、子域分析结果中预过滤无数据，减少后续处理成本。
• 构建自动化选词规则：将固定过滤器嵌任务流程，形成稳定的挖掘与评估标准。
• 校验字段容性：在正式调用分析接口前获取可用过滤字段，因字段名或类型不匹导致任务失败。