Business Listings 可用筛选条件

接口说明

本文说明 Business Listings API 可使用的筛选条件，以及筛选表达式的结构与写法。

请注意：

• 筛选条件的是 result 数组中的对象字段，使用时需要对应对象层级指定；
• 该接口用于获取当前端点支持的过滤参数；
• 本接口本身不产生调用费用。

接口地址

GET https://api.seermartech.cn/v3/business_data/business_listings/available_filters

调用后，接口会返回当前 Business Listings 端点支持的完整过滤参数列表。

计费说明

本接口不收费。

• 参考价约 ¥0.0000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

认证方式

请求头示例：

Authorization: Bearer smt_live_YOUR_KEY

响应结构

接口返回 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 数组中返回错误的任务数量
tasks	array	任务数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors
status_message	string	任务状态信息，完整列表参考 /v3/appendix/errors
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	GET 请求 URL 中传的参数
result	array	结果数组，当前端点可用于数据过滤的参数，参数按可用端点分组

筛选表达式说明

下述规则用于说明 Business Listings API 中 filters 参数的写法和可用操作符。

filters 字段

字段名	类型	说明
filters	array	结果过滤条件数组；可选；最多支持 8 个过滤条件；多个条件之间应使用逻辑运算符 and 或 or 连接

筛选表达式由以下部分组成：

• $results_array
• $parameter_field
• $filter_operator
• $filter_value

筛选条件中使用 . 和 , 作为分隔符。

筛选结构字段说明

字段名	类型	说明
$results_array	string	结果对象名称；可选；可用值：address_info、rating
$parameter_field	string	过滤字段名；可选；一旦使用过滤则为填；表示上级 $results_array 下需要筛选的字段
$filter_operator	string	过滤操作符；可选；一旦使用过滤则为填
$filter_value	num / string / bool / array.str	过滤值；可选；一旦使用过滤则为填

可用操作符

不同字段类型支持的操作符如下：

布尔类型 bool

• =
• <>

数值类型 num

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

字符串类型 str

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

字符串数组 array.str

• 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须传数组。

示例：

["value_1","value_2"]

regex / not_regex

• 支持使用字符串值；
• 正则语法采用 RE2 规范；
• regex 和 not_regex 的最大字符长度为 1000。

like / not_like

使用 like 和 not_like 时，建议合 % 通符以获得准确结果。

示例说明：

• %pizza%：返回 domain 字段中 “pizza” 的 business_listing 记录
• not_like合 %pizza%：排除 domain 字段中 “pizza” 的结果

获取可用筛选参数

下面是一个型请求，用于获取 Business Listings API 支持的过滤参数。

cURL 示例

curl -X GET "https://api.seermartech.cn/v3/business_data/business_listings/available_filters" \
 -H "Authorization: Bearer smt_live_YOUR_KEY"

Python 示例

import requests

url = "https://api.seermartech.cn/v3/business_data/business_listings/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/business_data/business_listings/available_filters",
 {
 method: "GET",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 },
 }
);

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

响应示例

{
 "version": "0.1.20250515",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0511 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "business_data",
 "function": "available_filters",
 "se": "business_listings"
 },
 "result": []
 }
 ]
}

返回结果说明

result 中会返回当前端点可用的过滤字段单。你可以基于这些字段，为 Business Listings 的查询接口构造筛选条件。

建议使用前调用一次 /v3/business_data/business_listings/available_filters，确认当前支持的字段名称、字段层级以及适的操作符类型，再将对应过滤条件应用到业务查询请求中。

错误码说明

• 顶层 status_code / status_message：表示整个请求的执行状态
• tasks[].status_code / tasks[].status_message：表示单个任务的执行状态
• 完整错误码与状态说明参考 /v3/appendix/errors

实用场景

• 筛选高评分商家：基于 rating 字段筛出评分更高的本地商户，用于本地 SEO 竞争分析与优质线索挖掘。
• 排除非目标域名：通过 domain 的 not_like、not_regex 等条件剔除无站点，提高商家数据洗效率。
• 锁定指定地区商户：结合 address_info 下的地址字段过滤目标城市、区域或邮编，支持区域化市场研究。
• 构建行业样本：筛选名称、域名或分类特征符合条件的商户集合，为本地搜索词库扩展提供样本。
• 校验筛选逻辑：在正式批量查询前获取可用过滤字段，降低字段写错、层级不匹或操作符不容导致的请求失败风险。