企业列表搜索（实时）

POST /v3/business_data/business_listings/search/live

接口概述

通过本接口可实时检索指定类目下的 Google Maps 企业列表信息，并返回企业地址、联系方式、评分、营业时间等本地商家数据。

返回结果会受到所选地理位置设置的影响。若需查看可用位置，请参考 /v3/business_data/business_listings/locations 接口。

请求方式：POST
接口地址：https://api.seermartech.cn/v3/business_data/business_listings/search/live
请求体格式：JSON 数组 [{ ... }]
频率限制：最高 2000 次 API 调用 / 分钟
计费说明：按请求计费，扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求参数

以下字段用于提交搜索任务。

字段名	类型	说明
`categories`	array	可选。商家类目数组，用于筛选企业列表；如不传，则返回指定位置下检索到的企业列表。最多支持 `10` 个类目。
`description`	string	可选。SERP 中描述，用于匹目标企业描述。最长 `200` 字符。
`title`	string	可选。SERP 中标题，即企业名称。最长 `200` 字符。
`is_claimed`	boolean	可选。是否返回已由商家所有在 Google Maps 上完成认领/验证的企业。
`location_coordinate`	string	可选。位置坐标，格式为 `"latitude,longitude,radius"`。 `latitude` 与 `longitude` 最多 `7` 位小数；`radius` 单位为（km），最小值 `1`，最大值 `100000`。示例：`53.476225,-2.243572,200`
`filters`	array	可选。结果过滤条件数组。最多可同时设置 `8` 个过滤条件；条件之间应使用逻辑运算符 `and` 或 `or` 连接。支持运算符：`regex`、`not_regex`、`<`、`<=`、`>`、`>=`、`=`、`<>`、`in`、`not_in`、`like`、`not_like`、`ilike`、`not_ilike`、`match`、`not_match`。在 `like` 与 `not_like` 中可使用 `%` 匹任意长度字符串。可通过 `/v3/business_data/business_listings/available_filters` 获取可用过滤字段。
`order_by`	array	可选。排序规则数组。排序字段可使用与 `filters` 相同的字段名。排序方式：`asc` 升序，`desc` 降序。单条请求最多支持 `3` 条排序规则。单个排序项格式示例：`"rating.value,desc"`
`limit`	integer	可选。返回的企业数量上限。默认值：`100`；最大值：`1000`。
`offset`	integer	可选。结果偏移量，默认值：`0`。如设为 `10`，则跳过前 10 条结果并返回后续结果。建议在获取不 `10000` 条结果时使用。
`offset_token`	string	可选。翻页令牌，用于后续请求。适合在单次任务需获取 `100000` 条结果时时。该值会在每次响应中返回。使用 `offset_token` 时余请求参数与前一次请求保持一致。
`tag`	string	可选。用户自定义任务标识，最长 `255` 字符。可用于结果对账与任务识别，响应中的 `data` 对象会原样返回该值。

过滤与排序说明

filters 格式

filters 为数组，可组合多个条件。每个条件通常采用如下结构：

json

[
 ["rating.value", ">", 3],
 "and",
 ["price_level", "=", "inexpensive"]
]

order_by 格式

order_by 为字符串数组，每项格式如下：

json

[
 "rating.value,desc",
 "title,asc"
]

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/business_data/business_listings/search/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",
 "order_by": ["rating.value,desc"],
 "filters": [
 ["rating.value", ">", 3]
 ],
 "limit": 3
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/business_data/business_listings/search/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",
 "order_by": ["rating.value,desc"],
 "filters": [
 ["rating.value", ">", 3]
 ],
 "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",
 order_by: ["rating.value,desc"],
 filters: [
 ["rating.value", ">", 3]
 ],
 limit: 3
 }
];

axios.post(
 "https://api.seermartech.cn/v3/business_data/business_listings/search/live",
 postData,
 {
 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 数组。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码。完整错误码体系见 `/v3/appendix/errors`
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	执行报错的任务数量
`tasks`	array	任务结果数组

tasks[] 字段

字段名	类型	说明
`id`	string	本平台任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态说明
`time`	string	任务执行耗时
`cost`	float	当前任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	原样返回请求参数
`result`	array	获取结果数组

result[] 字段

字段名	类型	说明
`total_count`	integer	与本次请求的数据库总结果数
`count`	integer	`items` 数组中的数量
`offset`	integer	当前返回结果偏移量
`offset_token`	string	后续翻页令牌
`items`	array	企业列表结果数组

items[] 字段说明

items 中的类型固定为 business_listing。

字段名	类型	说明
`type`	string	素类型，固定为 `business_listing`
`title`	string	企业名称
`original_title`	string	原始标题，未被 Google 翻译的名称
`description`	string	企业描述
`category`	string	企业主类目
`category_ids`	array	通用类目 ID，不随国家变化
`additional_categories`	array	附加类目
`cid`	string	Google 定义的本地商家唯一客户端 ID
`feature_id`	string	SERP素唯一标识
`address`	string	企业地址
`address_info`	object	地址拆分信息
`place_id`	string	地点唯一标识
`phone`	string	电话
`url`	string	企业官网或落地页 URL
`domain`	string	域名
`logo`	string	Google My Business 资料中的 logo 图片 URL
`main_image`	string	Google My Business 资料中的主图 URL
`total_photos`	integer	图片总数
`snippet`	string	附加简介信息
`latitude`	float	纬度
`longitude`	float	经度
`is_claimed`	boolean	是否已由所有认领
`attributes`	object	商家属性信息
`place_topics`	object	评论中高频提及的及提及次数
`rating`	object	评分信息
`hotel_rating`	integer	店星级，若无则为 `null`
`price_level`	string	价格等级，可能值：`inexpensive`、`moderate`、`expensive`、`very_expensive`
`rating_distribution`	object	1 星到 5 星评分分布
`people_also_search`	array	商家
`work_time`	object	营业时间信息
`popular_times`	object	热门时段信息
`local_business_links`	array	搜索结果中可直接与商家交互的链接
`contact_info`	array	联系方式列表
`check_url`	string	搜索引擎结果直达链接，用于核验结果
`last_updated_time`	string	数据最近更新时间，UTC 格式
`first_seen`	string	首次发现该商家记录的时间，UTC 格式

重要子对象说明

address_info

字段名	类型	说明
`borough`	string	行政区 / 区县
`address`	string	街道地址
`city`	string	城市
`zip`	string	邮编
`region`	string	DMA 区域
`country_code`	string	ISO 国家代码

rating

字段名	类型	说明
`rating_type`	string	评分类型，可为 `Max5`、`Percents`、`CustomMax`
`value`	integer / float	评分值
`votes_count`	integer	评价数
`rating_max`	integer	该评分类型的最大值

rating_distribution

字段名	类型	说明
`1`	integer	1 星评价数
`2`	integer	2 星评价数
`3`	integer	3 星评价数
`4`	integer	4 星评价数
`5`	integer	5 星评价数

work_time

字段名	类型	说明
`work_hours`	object	营业时间
`timetable`	object	每周营业时间表，按 `sunday` 至 `saturday` 返回
`current_status`	string	当前营业状态：`open`、`close`、`temporarily_closed`、`closed_forever`

营业时间段对象中：

字段名	类型	说明
`open.hour`	integer	开始小时，24 小时制
`open.minute`	integer	开始分钟
`close.hour`	integer	结束小时，24 小时制
`close.minute`	integer	结束分钟

popular_times

字段名	类型	说明
`popular_times_by_days`	object	每周每日的繁忙时段
`time.hour`	integer	小时，24 小时制
`time.minute`	integer	分钟
`popular_index`	integer	热门指数，范围 `0-100`，值越高表示越繁忙

local_business_links

字段名	类型	说明
`type`	string	交互类型，可能值：`reservation`、`order`、`delivery_services_element`、`menu`
`title`	string	素标题，通常为服务平台域名或名称
`url`	string	对应服务链接

contact_info

字段名	类型	说明
`type`	string	联系方式类型
`value`	string	SERP 展示的联系方式
`source`	string	数据来源

响应示例

json

{
 "version": "0.1.20240422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3282 sec.",
 "cost": 0.0109,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "business_data",
 "function": "search",
 "categories": [
 "pizza_restaurant"
 ],
 "description": "pizza",
 "title": "pizza",
 "is_claimed": true,
 "location_coordinate": "53.476225,-2.243572,10",
 "order_by": [
 "rating.value,desc"
 ],
 "filters": [
 ["rating.value", ">", 3]
 ],
 "limit": 3
 },
 "result": [
 {
 "items": [
 {
 "type": "business_listing",
 "title": "Pizza Mate",
 "category": "Pizza takeaway",
 "cid": "10964700581133624142",
 "feature_id": "0x487bb328c6bde12b:0x982a7115c6fd234e",
 "address": "Project, 53 22 Market Pl, Stockport SK1 1EU",
 "address_info": {
 "borough": null,
 "address": "Project, 53 22 Market Pl",
 "city": "Stockport",
 "zip": "SK1 1EU",
 "region": null,
 "country_code": "GB"
 },
 "place_id": "ChIJK-G9xiize0gRTiP9xhVxKpg",
 "url": "https://pizzamate.co.uk/",
 "domain": "pizzamate.co.uk",
 "total_photos": 6,
 "latitude": 53.4115499,
 "longitude": -2.1574226,
 "is_claimed": true,
 "rating": {
 "rating_type": "Max5",
 "value": 5,
 "votes_count": 7,
 "rating_max": null
 },
 "rating_distribution": {
 "1": 0,
 "2": 0,
 "3": 0,
 "4": 0,
 "5": 7
 },
 "work_time": {
 "work_hours": {
 "current_status": "closed_forever"
 }
 },
 "check_url": "https://www.google.co.uk/maps?cid=10964700581133624142&hl=en&gl=GB",
 "last_updated_time": "2023-09-17 10:03:04 +00:00",
 "first_seen": "2023-09-17 10:03:04 +00:00"
 },
 {
 "type": "business_listing",
 "title": "Four Side Vegan Pizza",
 "category": "Pizza restaurant",
 "phone": "+447565790366",
 "domain": "www.instagram.com",
 "rating": {
 "rating_type": "Max5",
 "value": 4.8,
 "votes_count": 20,
 "rating_max": null
 }
 },
 {
 "type": "business_listing",
 "title": "Rudy's Pizza Napoletana - Portland Street",
 "category": "Neapolitan restaurant",
 "phone": "+441615322922",
 "domain": "www.rudyspizza.co.uk",
 "price_level": "inexpensive",
 "rating": {
 "rating_type": "Max5",
 "value": 4.7,
 "votes_count": 568,
 "rating_max": null
 },
 "place_topics": {
 "toppings": 11,
 "drinks": 95,
 "pepperoni": 83
 },
 "work_time": {
 "work_hours": {
 "current_status": "open"
 }
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code=20000 表示请求成功。
各任务也会返回独立的 status_code 与 status_message。
建议同时校验：

HTTP 状态码
顶层 status_code
tasks_error
tasks[].status_code

完整错误码说明请参考 /v3/appendix/errors。

使用建议

小批量分页：当结果总量较小（如 1 万）时，优使用 offset。
大结果集拉取：当结果很多时，优使用 offset_token，可降低时风险。
参数一致性：若使用 offset_token，除 offset_token 本身外余参数与前序请求一致。
精准筛选：建议组合 categories、location_coordinate、filters 与 order_by 使用，以提升命中质量。
结果核验：可使用返回的 check_url 对搜索结果进行人工复核。

实用场景

筛选高评分门店：按类目和坐标范围抓取商家，并用 rating.value、votes_count 过滤，快速建立优质本地商家名单。
监测竞品本地覆盖：按城市或商圈拉取指定类目的商家分布，分析竞品门店密度、认领状态和价格带。
挖掘外链与联系方式：提取商家的官网域名、电话、联系信息，为本地 SEO 外联、渠道拓展和销售触达提供线索。
分析用户评价话题：使用 place_topics 和评分分布识别用户最的服务点与差评原因，优化和口碑管理。
优化营业时段运营：结合 work_time 与 popular_times 评估门店营业状态和繁忙时段，为投放时间、客服排班和本地活动策划提供依据。

企业列表搜索（实时） ​

接口概述 ​

请求参数 ​

过滤与排序说明 ​

filters 格式 ​

order_by 格式 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

items[] 字段说明 ​

重要子对象说明 ​

address_info ​

rating ​

rating_distribution ​

work_time ​

popular_times ​

local_business_links ​

contact_info ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

企业列表搜索（实时）

接口概述

请求参数

过滤与排序说明

filters 格式

order_by 格式

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

tasks[] 字段

result[] 字段

items[] 字段说明

重要子对象说明

address_info

rating

rating_distribution

work_time

popular_times

local_business_links

contact_info

响应示例

状态码与错误处理

使用建议

实用场景