SeerMarTech API 文档

主题

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

POST /v3/business_data/business_listings/categories_aggregation/live

接口说明 ​

商家列表分类聚合接口用于返回商家分类的聚合结果，每个分类下的实体数量、常见分类、国家分布、网站数量、服务属性以及评论主题词等信息。

返回结果会严格基于你提交的筛选条件，例如分类、标题、描述、认证状态、地理坐标范围以及初始数据过滤条件。

  • 请求方式：POST
  • 接口地址：https://api.seermartech.cn/v3/business_data/business_listings/categories_aggregation/live
  • 请求体格式：JSON（UTF-8）
  • 请求体结构：[{ ... }]
  • 调用频率：最高 2000 次/分钟
  • 计费方式：按请求计费，扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求参数 ​

以下为任务设置时可用字段。

字段名类型说明
categoriesarray商家分类。可选。指定后将基于这些分类搜索商家列表；如果不传，则返回指定位置下匹到的商家列表。最多可指定 10 个分类。
descriptionstringSERP素描述。可选。表示需要采集结果的商家实体描述，最长 200 字符。
titlestringSERP素标题。可选。表示需要采集结果的商家实体名称，最长 200 字符。
is_claimedboolean可选。表示该商家是否已由所有在 Google Maps 上完成认领/验证。
location_coordinatestringGPS 坐标。可选。格式为 "latitude,longitude,radius"。latitude 和 longitude 最多支持 7 位小数；radius 最小值为 1，最大值为 100000。示例：53.476225,-2.243572,200
initial_dataset_filtersarray初始数据过滤条件数组。可选。最多可同时添加 8 个过滤条件，并通过逻辑运算符 and、or 连接。支持操作符：regex、not_regex、<、<=、>、>=、=、<>、in、not_in、like、not_like、match、not_match。 like 和 not_like 支持使用 % 匹任意长度字符串。可通过 /v3/business_data/business_listings/available_filters 获取可用过滤器列表，过滤字段完整说明可参考 /v3/business_data/business_listings/filters/。
internal_list_limitinteger聚合分类数组中的最大返回数量。可选。默认值：10。
limitinteger返回的最大商家数量。可选。默认值：100；最大值：1000。
offsetinteger返回结果偏移量。可选。
tagstring用户自定义任务标识。可选。最大长度 255 字符。可用于请求与响应结果的，返回时可在响应的 data 对象中看到该值。

请求示例 ​

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"
}

data = [
 {
 "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=data)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 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({
 method: "post",
 url: "https://api.seermartech.cn/v3/business_data/business_listings/categories_aggregation/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组，每个任务对应一组结果。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。完整错误码见 /v3/appendix/errors。建议在业务系统中设计完善的异常处理机制。
status_messagestring通用状态信息。完整信息见 /v3/appendix/errors。
timestring执行耗时，单位秒。
costfloat本次请求总费用，单位 USD。可按人民币估算，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数。
tasks_errorinteger返回错误的任务数。
tasksarray任务数组。

tasks[] 字段 ​

字段名类型说明
idstring本平台任务唯一标识，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态信息。
timestring任务执行耗时，单位秒。
costfloat当前任务费用，单位 USD。
result_countintegerresult 数组中的结果数。
patharrayURL 路径。
dataobject与提交请求时相同的参数集合。
resultarray结果数组。

result[] 字段 ​

字段名类型说明
total_countinteger数据库中与当前请求的结果总数。
countintegeritems 数组中的数量。
offsetinteger当前返回分类结果的偏移量。
offset_tokenstring后续请求分页令牌。在新任务中传该 offset_token 可获取初始任务的后续结果；每个后续任务的 offset_token 均唯一。
itemsarray聚合结果项数组。可能的类型：business_category。

items[] 字段 ​

字段名类型说明
typestring素类型，固定为 business_category。
categoriesarray商家分类。表示最能描述该分类簇的 Google My Business 通用分类。
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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3200 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": 3,
 "count": 3,
 "offset": 0,
 "offset_token": "example_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,
 "italian_restaurant": 7,
 "neapolitan_restaurant": 6,
 "fast_food_restaurant": 4,
 "meal_takeaway": 3,
 "vegan_restaurant": 3
 },
 "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,
 "has_no_contact_delivery": 20,
 "serves_dessert": 20,
 "serves_dinner": 18,
 "accepts_reservations": 17,
 "has_wheelchair_accessible_entrance": 17
 },
 "top_place_topics": {
 "price": 9,
 "order": 8,
 "money": 7,
 "atmosphere": 6,
 "dominos": 6,
 "vegan": 6,
 "cold": 5,
 "kids": 5,
 "phone": 5,
 "dough": 4
 }
 }
 },
 {
 "type": "business_category",
 "categories": ["pizzatakeaway"],
 "aggregation": {
 "top_categories": {
 "pizza_restaurant": 14,
 "pizzatakeaway": 14,
 "pizza_delivery_service": 8,
 "restaurant": 8,
 "fast_food_restaurant": 3,
 "family_restaurant": 2,
 "italian_restaurant": 2,
 "meal_takeaway": 2,
 "vegan_restaurant": 2,
 "buffet_restaurant": 1
 },
 "top_countries": {
 "GB": 14
 },
 "websites_count": 7,
 "count": 14,
 "top_attributes": {
 "has_delivery": 14,
 "has_takeout": 14,
 "feels_casual": 13,
 "pay_debit_card": 12,
 "pay_mobile_nfc": 12,
 "has_no_contact_delivery": 10,
 "accepts_reservations": 9,
 "is_transgender_safespace": 9,
 "serves_dessert": 9,
 "serves_late_night_food": 8
 },
 "top_place_topics": {
 "price": 5,
 "order": 4,
 "buffet": 3,
 "ice cream": 3,
 "kids": 3,
 "money": 3,
 "pay": 3,
 "the pizza": 3,
 "app": 2,
 "call": 2
 }
 }
 },
 {
 "type": "business_category",
 "categories": ["restaurant"],
 "aggregation": {
 "top_categories": {
 "pizza_restaurant": 12,
 "restaurant": 12,
 "pizzatakeaway": 8,
 "pizza_delivery_service": 5,
 "italian_restaurant": 3,
 "neapolitan_restaurant": 3,
 "family_restaurant": 2,
 "vegan_restaurant": 2,
 "buffet_restaurant": 1,
 "delivery_service": 1
 },
 "top_countries": {
 "GB": 12
 },
 "websites_count": 3,
 "count": 12,
 "top_attributes": {
 "has_delivery": 12,
 "has_takeout": 12,
 "accepts_reservations": 11,
 "feels_casual": 11,
 "is_transgender_safespace": 11,
 "pay_debit_card": 11,
 "pay_mobile_nfc": 11,
 "serves_dessert": 10,
 "has_no_contact_delivery": 8,
 "has_wheelchair_accessible_entrance": 8
 },
 "top_place_topics": {
 "the pizza": 4,
 "buffet": 3,
 "ice cream": 3,
 "incredible pizza": 3,
 "kids": 3,
 "order": 3,
 "pay": 3,
 "vegan": 3,
 "app": 2,
 "atmosphere": 2
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

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

常见处理建议：

场景建议
请求参数格式错误检查 JSON 数组结构是否为 [{...}]，以及字段类型是否正确
坐标范围无效检查 location_coordinate 是否为 latitude,longitude,radius 格式，且 radius 在范围
过滤器无效调用 /v3/business_data/business_listings/available_filters 获取可用过滤字段
结果分页使用返回的 offset_token 发起后续请求以获取下一批结果

计费说明 ​

该接口按请求计费。原始示例响应中的 cost 为 0.0109 USD，则可折算为：

  • 参考价约 ¥0.1744 / 次

请注意：

  • 上述金额为基于示例响应的参考换算
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

实用场景 ​

  • 分析行业分类结构：按地区或聚合同类商家分类，快速识别一个细分市场中最常见的业态组合。
  • 筛选高价值本地商家样本：结合 is_claimed、评分过滤器和地理范围，定位更成熟、更规范的商家群体用于竞品研究。
  • 提炼用户点：通过 top_place_topics 汇总评论高频词，识别最心的价格、服务、产品和体验问题。
  • 洞察服务能力分布：利用 top_attributes 统计、外带、预订、支付方式等服务属性，评估区域市场服务成熟度。
  • 本地 SEO 选类与布局：根据 top_categories 和评论主题词，优化商家分类选择、落地页和本地化策略。

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

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