SeerMarTech API 文档

主题

商家列表类别聚合（实时） ​

POST /v3/business_data/business_listings/categories_aggregation/live

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

/v3/business_data/business_listings/categories_aggregation/live

商家列表类别聚合接口用于返回商家类别分组及各类别中的实体数量。返回结果会根据请求中指定的类别、地点、标题、描述及筛选条件进行聚合。

每次请求支持提交 1 个任务。所有 POST 数据使用 UTF-8 编码的 JSON 格式，并以 JSON 数组作为请求体。平台限流以认证说明中的 30/60/120 次/分钟规则为准，同时进行的请求数最多为 30 个。

计费说明 ​

接口按请求计费。参考价约 ¥0.0785 / 次，费用可能因任务参数和数据量而变化。

示例响应中的 cost: 0.0109 为平台返回的历史示例值，折算约为 ¥0.0785供参考。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

请求体是数组格式：

json
[
  {
    "categories": [
      "pizza_restaurant"
    ],
    "description": "pizza",
    "title": "pizza",
    "is_claimed": true,
    "location_coordinate": "53.476225,-2.243572,10",
    "initial_dataset_filters": [
      [
        "rating.value",
        ">",
        3
      ]
    ],
    "internal_list_limit": 10,
    "limit": 3
  }
]

任务参数 ​

参数名类型填说明
categoriesarray否商家类别。指定后，本接口将根据这些类别搜索商家列表；未指定时，将返回指定地点发现的商家列表。最多可指定 10 个类别。
descriptionstring否SERP素中的描述，用于匹商家实体。最多 200 个字符。
titlestring否SERP素中的标题，用于匹商家实体。最多 200 个字符。
is_claimedboolean否是否表示该商家已由所有在 Google 地图中完成验证。
location_coordinatestring否地理坐标及半径，格式为 latitude,longitude,radius。
initial_dataset_filtersarray否初始数据集筛选条件。最多同时设置 8 个筛选条件。
internal_list_limitinteger否聚合类别中数组的最大数量。默认值为 10。
limitinteger否返回的最大商家数量。默认值为 100，最大值为 1000。
offsetinteger否返回结果的偏移量。
tagstring否用户自定义任务标识，最多 255 个字符。可用于识别任务并与响应结果进行匹。提交的值会在响应 data 对象中返回。

location_coordinate 格式 ​

location_coordinate须使用以下格式：

text
纬度,经度,半径

约束如下：

  • 纬度和经度最多支持 7 位小数；
  • radius 最小值为 1；
  • radius 最大值为 100000；
  • 示例：53.476225,-2.243572,200。

initial_dataset_filters 筛选条件 ​

筛选条件通常使用以下数组格式：

json
[
  [
    "rating.value",
    ">",
    3
  ],
  "and",
  [
    "reviews_count",
    ">=",
    10
  ]
]

支持的运算符：

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

like 和 not_like 支持使用 % 匹零个或多个字符。

可通过以下接口获取可用筛选字段：

/v3/business_data/business_listings/available_filters

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/business_data/business_listings/categories_aggregation/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "categories": [
        "pizza_restaurant"
      ],
      "description": "pizza",
      "title": "pizza",
      "is_claimed": true,
      "location_coordinate": "53.476225,-2.243572,10",
      "initial_dataset_filters": [
        [
          "rating.value",
          ">",
          3
        ]
      ],
      "internal_list_limit": 10,
      "limit": 3
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/business_data/business_listings/categories_aggregation/live"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "categories": ["pizza_restaurant"],
        "description": "pizza",
        "title": "pizza",
        "is_claimed": True,
        "location_coordinate": "53.476225,-2.243572,10",
        "initial_dataset_filters": [
            ["rating.value", ">", 3]
        ],
        "internal_list_limit": 10,
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    categories: ["pizza_restaurant"],
    description: "pizza",
    title: "pizza",
    is_claimed: true,
    location_coordinate: "53.476225,-2.243572,10",
    initial_dataset_filters: [
      ["rating.value", ">", 3]
    ],
    internal_list_limit: 10,
    limit: 3
  }
];

axios
  .post(
    "https://api.seermartech.cn/v3/business_data/business_listings/categories_aggregation/live",
    payload,
    {
      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);
  });

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层响应字段 ​

字段名类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。成功时通常为 20000。
status_messagestring通用状态说明。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

tasks 任务字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常位于 10000 至 60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 URL 路径。
dataobject创建任务时提交的参数。
resultarray类别聚合结果数组。

result 字段 ​

字段名类型说明
total_countinteger数据库中与请求条件的结果总数。
countinteger当前 items 数组中的数量。
offsetinteger当前返回类别在完整结果集中的偏移量。
offset_tokenobject后续分页请求使用的令牌。将该令牌提交到新任务中，可获取当前任务的后续结果。每个后续任务的 offset_token 均唯一性。
itemsarray聚合结果项数组。

items 字段 ​

字段名类型说明
typestring结果类型。当前支持 business_category。
categoriesarray商家类别。表示最能描述类别集群的 Google 商家类别。
aggregationobject类别聚合数据。

aggregation 字段 ​

字段名类型说明
top_categoriesobject出现频率最高的类别及商家数量。
top_countriesobject商家数量最多的国家或地区代码及对应数量。
websites_countinteger不重复网站数量。
countinteger不重复实体数量。
top_attributesobject出现频率最高的服务属性及提及该属性的实体数量，例如是否提供、是否支持外带等。
top_place_topicsobject顾客评论中最常提及的及提及这些的评论数量，通常用于分析产品、服务和消费体验。

响应示例 ​

json
{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3505 sec.",
  "cost": 0.0109,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2800 sec.",
      "cost": 0.0109,
      "result_count": 1,
      "path": [
        "v3",
        "business_data",
        "business_listings",
        "categories_aggregation",
        "live"
      ],
      "data": {
        "api": "business_data",
        "function": "categories_aggregation",
        "categories": [
          "pizza_restaurant"
        ],
        "description": "pizza",
        "title": "pizza",
        "is_claimed": true,
        "location_coordinate": "53.476225,-2.243572,10",
        "initial_dataset_filters": [
          [
            "rating.value",
            ">",
            3
          ]
        ],
        "limit": 3
      },
      "result": [
        {
          "total_count": 32,
          "count": 1,
          "offset": 0,
          "offset_token": {},
          "items": [
            {
              "type": "business_category",
              "categories": [
                "pizza_restaurant"
              ],
              "aggregation": {
                "top_categories": {
                  "pizza_restaurant": 32,
                  "pizzatakeaway": 14,
                  "restaurant": 12,
                  "pizza_delivery_service": 11,
                  "delivery_service": 7
                },
                "top_countries": {
                  "GB": 32
                },
                "websites_count": 18,
                "count": 32,
                "top_attributes": {
                  "has_delivery": 32,
                  "has_takeout": 32,
                  "feels_casual": 28,
                  "pay_debit_card": 26,
                  "pay_mobile_nfc": 23
                },
                "top_place_topics": {
                  "price": 9,
                  "order": 8,
                  "money": 7,
                  "atmosphere": 6,
                  "vegan": 6
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

如果请求或任务处理失败，请根据顶层或任务级别的 status_code 和 status_message 进行错误处理。

实用场景 ​

  • 聚合本地商家类别，统计目标区域类别的数量与类别分布，为本地 SEO 类别规划提供依据。
  • 分析竞争商家的服务属性，识别、外带、预约、支付方式等高频属性，指导商家资料和落地页优化。
  • 提取顾客评论主题，统计价格、服务、产品等高频评论，为选题和用户体验改进提供数据支持。
  • 比较不同国家或地区的商家分布，通过 top_countries 识别业务覆盖集中区域，市场和区域 SEO 决策。
  • 筛选高质量商家样本，结合评分、评论数等 initial_dataset_filters 条件构建竞争对手数据集，提升竞品分析的准确性。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API