商家列表实时搜索

POST /v3/business_data/business_listings/search/live

接口说明

POST /v3/business_data/business_listings/search/live

本接口用于实时搜索指定位置和类别下的商家列表，返回商家地址、联系方式、评分、营业时间、价格等级、热门时段及本地商业信息。结果范围和语言等位置取决于请求中指定的位置参数。

所有 POST 请求体使用 UTF-8 编码的 JSON 格式，并且顶层是数组。每次 Live API 请求只能提交 1 个任务。

平台限流以认证说明中的 30/60/120 次/分钟规则为准

单次请求最多 1 个任务
同时执行的请求数最多为 30 个
categories 最多可传 10 个类别
filters 最多可设置 8 个过滤条件
order_by 最多可设置 3 条排序规则

计费说明

按请求计费。示例响应中的 cost: 0.0109 原为金额，按参考汇率折算约为 ¥0.0785。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

任务参数

参数	类型	填	说明
`categories`	array	否	商家类别。用于限定搜索的商家类型，最多 10 个。不传时，返回指定位置找到的商家。
`description`	string	否	商家描述。最多 200 个字符。
`title`	string	否	商家名称。最多 200 个字符。
`is_claimed`	boolean	否	是否返回已由商家所有验证的商家。
`location_coordinate`	string	否	搜索中心点和半径，格式为 `纬度,经度,半径`。半径单位为千米。
`filters`	array	否	结果过滤条件。最多 8 个条件，条件之间使用 `and` 或 `or` 连接。
`order_by`	array	否	结果排序规则。可使用与 `filters` 相同的字段，最多 3 条。
`limit`	integer	否	返回的最大商家数量。默认 `100`，最大 `1000`。
`offset`	integer	否	结果偏移量。默认 `0`。例如设置为 `10` 时，跳过结果数组中的前 10 条记录。建议在获取不 10,000 条结果时使用。
`offset_token`	string	否	分页令牌。用于获取后续结果，适合 100,000 条结果的场景。使用时，除 `offset_token` 外的请求参数与上一次请求一致。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

`location_coordinate` 格式

text

53.476225,-2.243572,200

规则如下：

纬度和经度最多保留 7 位小数
半径最小值为 1
半径最大值为 100000
半径单位为千米

`filters` 过滤条件

支持以下运算符：

text

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

过滤条件示例：

json

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

使用 like 或 not_like 时，可以使用 % 匹任意长度的字符串。例如：

json

["title", "like", "%pizza%"]

可通过以下接口获取可用的过滤字段：

text

GET /v3/business_data/business_listings/available_filters

`order_by` 排序规则

排序参数格式为：

text

字段名,排序方向

排序方向支持：

asc：升序
desc：降序

示例：

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

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

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (data.get("status_code"), data.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",
    order_by: ["rating.value,desc"],
    filters: [["rating.value", ">", 3]],
    limit: 3,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/business_data/business_listings/search/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 是任务结果数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	总体状态码。`20000` 表示成功。
`status_message`	string	总体状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中执行失败的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 URL 路径。
`data`	object	本次任务使用的请求参数。
`result`	array	搜索结果数组。

`result` 字段

字段	类型	说明
`total_count`	integer	与请求条件的结果总数。
`count`	integer	`items` 数组中的数量。
`offset_token`	string/object	后续分页令牌。将用于下一次请求时，可获取当前任务的后续结果。
`items`	array	商家搜索结果数组。

商家结果字段

items 中每个商家的 type 固定为 business_listing。

字段	类型	说明
`type`	string	结果类型，固定为 `business_listing`。
`title`	string	商家名称。
`original_title`	string	未经过平台翻译的原始名称。
`description`	string	商家描述。
`category`	string	商家主类别。
`category_ids`	array	通用的类别 ID。
`additional_categories`	array	商家的类别。
`cid`	string	地方商家的唯一标识。
`feature_id`	string	搜索结果的唯一标识。
`address`	string	商家完整地址。
`address_info`	object	地址组成信息。
`place_id`	string	地点唯一标识。
`phone`	string	商家电话号码。
`url`	string	商家绝对 URL。
`domain`	string	商家网站域名。
`logo`	string	商家资料中的 Logo 地址。
`main_image`	string	商家主图地址。
`total_photos`	integer	商家资料中的图片总数。
`snippet`	string	商家附加信息或搜索结果摘要。
`latitude`	float	商家纬度，例如 `51.584091`。
`longitude`	float	商家经度，例如 `-0.3136592`。
`is_claimed`	boolean	商家是否已完成所有验证。
`attributes`	object	基于用户反馈整理的服务属性。
`place_topics`	object	用户评价中出现频率较高的产品或服务及提及次数。
`rating`	object	商家评分信息。
`hotel_rating`	integer	店星级，范围为 1 至 5；无数据时为 `null`。
`price_level`	string	价格等级：`inexpensive`、`moderate`、`expensive`、`very_expensive`；无数据时为 `null`。
`rating_distribution`	object	1 至 5 星评价数量分布。
`people_also_search`	array	商家列表。
`work_time`	object	营业时间信息。
`popular_times`	object	商家繁忙时段信息。
`local_business_links`	array	可直接与商家互动的链接。
`contact_info`	array	搜索结果中展示的联系方式。
`source`	string	数据来源。
`check_url`	string	对应搜索结果页面的直接 URL，可用于人工核验。
`last_updated_time`	string	数据最后更新时间，UTC 格式。
`first_seen`	string	首次发现该商家记录的时间，UTC 格式。

`address_info` 地址字段

字段	类型	说明
`borough`	string	商家所在的行政区或地区。
`address`	string	街道地址。
`city`	string	城市名称。
`zip`	string	邮政编码。
`region`	string	地区或区域信息。
`country_code`	string	ISO 国家或地区代码。

`attributes` 服务属性

字段	类型	说明
`available_attributes`	object	商家可以提供的服务属性。
`unavailable_attributes`	object	商家无法提供的服务属性。

`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 星评价数量。

`people_also_search` 商家字段

数组中的每个：

字段	类型	说明
`cid`	string	商家的唯一标识。
`feature_id`	string	搜索结果唯一标识。
`title`	string	商家名称。
`rating`	object	商家的评分对象，字段结构与主结果中的 `rating` 相同。

`work_time` 营业时间字段

字段	类型	说明
`work_hours`	object	营业时间。
`work_hours.timetable`	object	每周营业时间表。
`work_hours.current_status`	string	当前状态：`open`、`close`、`temporarily_closed`、`closed_forever`。

每天的营业时间字段 sunday、monday、tuesday、wednesday、thursday、friday 和 saturday。时间段结构如下：

字段	类型	说明
`open`	object	开门时间。
`open.hour`	integer	24 小时制小时数。
`open.minute`	integer	分钟数。
`close`	object	门时间。
`close.hour`	integer	24 小时制小时数。
`close.minute`	integer	分钟数。

`popular_times` 热门时段字段

字段	类型	说明
`popular_times_by_days`	object	按星期划分的繁忙时段。
`time`	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	搜索结果中展示的联系方式，例如 `+119797979736`。

响应示例

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": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.3100 sec.",
      "cost": 0.0109,
      "result_count": 1,
      "path": [
        "v3",
        "business_data",
        "business_listings",
        "search",
        "live"
      ],
      "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": [
        {
          "total_count": 3,
          "count": 3,
          "offset_token": null,
          "items": [
            {
              "type": "business_listing",
              "title": "Rudy's Pizza Napoletana - Portland Street",
              "original_title": null,
              "description": "For us it’s all about the pizza.",
              "category": "Neapolitan restaurant",
              "category_ids": ["pizza_restaurant"],
              "additional_categories": [],
              "cid": "10486315685157041285",
              "feature_id": "0x487bb1340d960e25:0x9186e08e88647485",
              "address": "30 Portland St, Manchester M1 4GS",
              "address_info": {
                "borough": null,
                "address": "30 Portland St",
                "city": "Manchester",
                "zip": "M1 4GS",
                "region": null,
                "country_code": "GB"
              },
              "place_id": "ChIJJQ6WDTSxe0gRhXRkiI7ghpE",
              "phone": "+441615322922",
              "url": "http://www.rudyspizza.co.uk/",
              "domain": "www.rudyspizza.co.uk",
              "logo": "https://lh3.googleusercontent.com/example-logo",
              "main_image": "https://lh5.googleusercontent.com/example-image",
              "total_photos": 345,
              "snippet": "30 Portland St, Manchester M1 4GS",
              "latitude": 53.4790412,
              "longitude": -2.238241,
              "is_claimed": true,
              "attributes": {
                "available_attributes": {
                  "service_options": [],
                  "offerings": [],
                  "dining_options": []
                },
                "unavailable_attributes": null
              },
              "place_topics": {
                "toppings": 11,
                "drinks": 95,
                "pepperoni": 83
              },
              "rating": {
                "rating_type": "Max5",
                "value": 4.7,
                "votes_count": 568,
                "rating_max": null
              },
              "hotel_rating": null,
              "price_level": "inexpensive",
              "rating_distribution": {
                "1": 11,
                "2": 6,
                "3": 24,
                "4": 73,
                "5": 454
              },
              "people_also_search": [],
              "work_time": {
                "work_hours": {
                  "timetable": {
                    "sunday": [],
                    "monday": [],
                    "tuesday": [],
                    "wednesday": [],
                    "thursday": [],
                    "friday": [],
                    "saturday": []
                  },
                  "current_status": "open"
                }
              },
              "popular_times": null,
              "local_business_links": null,
              "contact_info": [],
              "check_url": "https://www.google.co.uk/maps?cid=10486315685157041285&hl=en&gl=GB",
              "last_updated_time": "2024-03-27 17:32:19 +00:00",
              "first_seen": "2023-09-17 10:03:04 +00:00"
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

请根据顶层 status_code、任务级 status_code 和对应的 status_message 判断请求及任务是否成功。建议客户端同时处理以下：

HTTP 请求失败
顶层 status_code 非 20000
tasks_error 大于 0
单个任务的 status_code 非 20000
result、items 或分页字段为空
offset_token 失效或与上一次请求参数不匹

完整错误码列表请参考 /v3/appendix/errors。

实用场景

搜索指定区域的目标商家，批量获取商家名称、地址、电话和网站，用于本地 SEO 竞品库和潜客名单建设。
筛选高评分或已认证商家，识别区域口碑较好的竞争对手，支持本地市场调研和客户拓展。
分析商家类别与服务属性，对比不同商家的餐饮、、预约和无障碍服务，本地商业供给分析。
监测商家营业状态与热门时段，判断门店是否营业、何时客流较高，为本地广告投放和运营排期提供依据。
提取评价主题与评分分布，统计用户频繁提及的产品和服务，用于选题、评价优化和竞争差异分析。

商家列表实时搜索 ​

接口说明 ​

计费说明 ​

请求参数 ​

任务参数 ​

location_coordinate 格式 ​

filters 过滤条件 ​

order_by 排序规则 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

商家结果字段 ​

address_info 地址字段 ​

attributes 服务属性 ​

rating 评分字段 ​

rating_distribution 评分分布 ​

people_also_search 商家字段 ​

work_time 营业时间字段 ​

popular_times 热门时段字段 ​

local_business_links 商家互动链接 ​

contact_info 联系方式 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

商家列表实时搜索

接口说明

计费说明

请求参数

任务参数

`location_coordinate` 格式

`filters` 过滤条件

`order_by` 排序规则

请求示例

curl

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 字段

商家结果字段

`address_info` 地址字段

`attributes` 服务属性

`rating` 评分字段

`rating_distribution` 评分分布

`people_also_search` 商家字段

`work_time` 营业时间字段

`popular_times` 热门时段字段

`local_business_links` 商家互动链接

`contact_info` 联系方式

响应示例

状态码与异常处理

实用场景