Business Listings API 过滤器

GET /v3/business_data/business_listings/available_filters

本页介绍 Business Listings API 可使用的过滤器。主接口契约为：GET /v3/business_data/business_listings/available_filters。调用该接口可获取 Business Listings 端点支持的完整过滤参数列表。

过滤器与响应 result 数组中的特定对象联，使用时对应对象的字段路径进行。

计费说明

调用本接口不收取费用，响应中的 cost 通常为 0。

获取可用过滤器

请求

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

curl 示例

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

响应说明

接口返回 JSON 格式数据 tasks 数组。每个任务当前请求的处理状态，以及 result 数组中的可用过滤参数定义。

字段名	类型	说明
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	可用过滤参数列表，参数按可使用的 API 端点分组

响应示例

{
  "version": "0.1.20250515",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0511 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",
        "business_data",
        "business_listings",
        "available_filters"
      ],
      "data": {
        "api": "business_data",
        "function": "available_filters",
        "se": "business_listings"
      },
      "result": [
        {
          "endpoint": "business_listings",
          "filters": []
        }
      ]
    }
  ]
}

> 实响应中的 result 将返回完整的可用过滤参数定义，并按可使用的端点进行分组。

过滤器结构

过滤参数通过请求体中的 filters 字段传递。过滤器是一个数组，最多可同时设置 8 个过滤条件；多个条件之间使用逻辑运算符 and 或 or。

通用结构如下：

[
  "and",
  [
    [
      "$results_array.$parameter_field",
      "$filter_operator",
      "$filter_value"
    ]
  ]
]

例如，以下过滤器表示：保留 address_info 对象中 rating 大于或等于 4 的结果：

[
  "and",
  [
    [
      "address_info.rating",
      ">=",
      4
    ]
  ]
]

字段路径使用 . 连接上级结果对象与字段；过滤器数组中的使用 JSON 标准的逗号分隔。

过滤器字段说明

字段名	类型	说明
filters	array	结果过滤条件数组，可选字段；最多可添加 8 个过滤条件。使用多个条件时，指定 and 或 or 逻辑运算符
$results_array	string	过滤器所属的结果对象，可选字段；当前支持 address_info、rating 等结果对象，以接口返回的可用过滤器列表为准
$parameter_field	string	结果对象中的过滤字段，可选字段；启用过滤器时为填
$filter_operator	string	过滤运算符，可选字段；启用过滤器时为填
$filter_value	number/string/boolean/array[string]	过滤值，可选字段；启用过滤器时为填

过滤运算符

过滤运算符取决于字段类型：

字段类型	支持的运算符
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	<、>

过滤值规则

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

• time 类型的值使用以下格式：

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

  示例：

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

• regex 和 not_regex 支持使用 RE2 正则表达式语法。

• regex 和 not_regex 的表达式最多可 1000 个字符。

• 使用 like 和 not_like 时，应在匹中 % 通符，以获得准确结果。

过滤示例

返回 domain 字段中 pizza 的 Business Listings：

[
  "and",
  [
    [
      "domain",
      "like",
      "%pizza%"
    ]
  ]
]

排除 domain 字段中 pizza 的域名：

[
  "and",
  [
    [
      "domain",
      "not_like",
      "%pizza%"
    ]
  ]
]

使用多个条件时，可通过 and 或 or 组合：

[
  "and",
  [
    [
      "address_info.rating",
      ">=",
      4
    ],
    [
      "domain",
      "like",
      "%pizza%"
    ]
  ]
]

状态码与错误处理

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

• status_code：请求级或任务级状态码。
• status_message：对应的状态说明。
• tasks_error：返回错误的任务数量。
• tasks[].result：任务成功时的结果数据。

接时，应同时检查顶层 status_code 与 tasks[].status_code。计费及扣费信息以响应头 X-SeerMarTech-Charge-CNY 为准。

实用场景

• 筛选高评分商家：使用 rating 等数值字段过滤评分较高的商家，优分析潜在合作对象和本地搜索竞争对手。
• 定位特定类型商家：使用 like、ilike 或正则表达式匹域名及文本字段，快速提取目标行业或品牌商家。
• 排除无结果：使用 not_like、not_in 或 not_match理不符合业务范围的商家数据，提高后续分析准确性。
• 组合多维条件：使用 and、or 组合评分、地址及文本条件，构建本地 SEO 竞品筛选规则。
• 按时间筛选数据：使用 time 类型字段过滤指定时间范围的记录，支持商家数据更新监控和趋势分析。