设置 Google 商家信息实时任务

POST /v3/business_data/google/my_business_info/live

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

/v3/business_data/google/my_business_info/live

本接口用于获取指定商家的 Google 商家信息。返回结果受所选搜索位置和语言影响。位置和语言列表可分别通过以下接口查询：

/v3/business_data/google/locations
/v3/business_data/google/languages

计费与请求限制

设置任务时会产生费用。示例响应中的原始任务费用 0.0054 按参考汇率折算约为 ¥0.0389 / 次，价格可能因平台计费策略而变化。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求要求：

请求体使用 UTF-8 编码的 JSON。
请求体格式为 JSON 数组：[{ ... }]。
每次实时 API 调用只能提交一个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
同时进行的调用数量最多为 30 个。

请求参数

参数	类型	填	说明
`keyword`	string	是	商家名称或本地商户，最多 700 个字符。也可传 `cid` 或 `place_id`。示例：`cid:194604053573767737`、`place_id:GhIJQWDl0CIeQUARxks3icF8U8A`。 `%##` 会被解码，字符 `+` 会被解码为空格。如果中需要使用 `%`，请写为 `%25`。
`location_name`	string	条件填	搜索位置的完整名称。未指定 `location_code` 或 `location_coordinate` 时填。示例：`London,England,United Kingdom`。使用该参数时，不应同时传另外两个位置参数。
`location_code`	integer	条件填	搜索位置代码。未指定 `location_name` 或 `location_coordinate` 时填。示例：`2840`。
`location_coordinate`	string	条件填	GPS 坐标，格式为 `纬度,经度,半径`，例如 `53.476225,-2.243572,200`。纬度和经度最多 7 位小数；半径最小值为 `199.9`，最大值为 `199999`。使用该参数时，不应同时传另外两个位置参数。
`language_name`	string	条件填	搜索语言的完整名称。未指定 `language_code` 时填。示例：`English`。
`language_code`	string	条件填	搜索语言代码。未指定 `language_name` 时填。示例：`en`。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在任务的 `data` 对象中，可用于任务与结果。

位置代码和语言代码可通过以下接口获取：

GET /v3/business_data/google/locations
GET /v3/business_data/google/languages

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/business_data/google/my_business_info/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_code": 1023191,
      "language_code": "en",
      "keyword": "RustyBrick, Inc."
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/business_data/google/my_business_info/live"

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

payload = [
    {
        "location_code": 1023191,
        "language_code": "en",
        "keyword": "RustyBrick, Inc.",
    }
]

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

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

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    location_name: "New York,New York,United States",
    language_name: "English",
    keyword: "RustyBrick, Inc.",
    tag: "some_string_123",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/business_data/google/my_business_info/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	通用响应状态码。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	通用响应信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	返回错误的任务数量。
`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` 字段

字段	类型	说明
`keyword`	string	请求中的。返回时会对 `%##` 解码，并将 `+` 解码为空格。如果请求中传 `cid`，此处会返回对应的 `cid`。
`se_domain`	string	请求中使用的搜索引擎域名。
`location_code`	integer	请求中的位置代码。
`language_code`	string	请求中的语言代码。
`check_url`	string	直接指向搜索结果的 URL，可用于核验结果准确性。
`datetime`	string	获取结果的 UTC 时间，格式为 `yyyy-mm-dd hh-mm-ss +00:00`。
`item_types`	array	结果项类型，可能 `google_business_info`。
`items_count`	integer	`items` 数组中的数量。
`items`	array	商家信息结果项。

`items` 商家信息字段

字段	类型	说明
`type`	string	结果类型，固定为 `google_business_info`。
`rank_group`	integer	同类型结果中的组排名。不同类型之间不计该排名。
`rank_absolute`	integer	所有结果中的绝对排名。
`position`	string	结果在搜索结果页中的对齐位置。
`title`	string	商家名称。
`original_title`	string	未经搜索引擎翻译的原始标题。
`description`	string	商家描述。
`category`	string	商家主类别。
`category_ids`	array	通用的类别 ID，不随国家变化。
`additional_categories`	array	商家的类别。
`cid`	string	商家的唯一标识，可用于调用 `/v3/reviews/google/overview/` 获取评论数据。
`feature_id`	string	结果项在搜索结果页中的唯一标识。
`address`	string	商家完整地址。
`address_info`	object	地址拆分信息，见下表。
`place_id`	string	商家在地图服务中的唯一地点标识。
`phone`	string	商家电话号码。
`url`	string	商家官网绝对 URL。
`contact_url`	string	首选联系页面 URL。
`contributor_url`	string	用户或实体的本地向导资料页 URL，如可用。
`book_online_url`	string	在线预约或下单 URL。
`domain`	string	商家域名。
`logo`	string	商家资料中的 Logo URL。
`main_image`	string	商家资料中的主图 URL。
`total_photos`	integer	商家资料中的图片总数。
`snippet`	string	商家附加信息。
`latitude`	float	商家地图坐标纬度。
`longitude`	float	商家地图坐标经度。
`is_claimed`	boolean	商家是否已由所有验证认领。
`attributes`	object	基于用户反馈和商家类别整理的服务属性。
`place_topics`	object	评论中出现频率较高的主题及评论数量。
`rating`	object	商家评分信息。
`rating_distribution`	object	1 星至 5 星的评分分布。
`people_also_search`	array	用户还搜索的商家。
`work_time`	object	商家营业时间及当前营业状态。
`popular_times`	object	商家繁忙时段信息。
`local_business_links`	array	搜索结果页中可直接与商家互动的链接。
`is_directory_item`	boolean	是否属于同一地址下的商家目录。父级目录项时可能为 `null`。
`directory`	array	同一地址下商家的目录信息。
`services`	array	商家提供的服务及价格信息。
`price_level`	string	价格等级：`inexpensive`、`moderate`、`expensive`、`very_expensive`；无数据时为 `null`。
`hotel_rating`	integer	店星级，范围为 1–5；无数据时为 `null`。
`local_justifications`	array	用于说明商家为何匹搜索词的本地结果文本片段。

`address_info`

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

`attributes`

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

属性对象可能：

from_the_business
service_options
accessibility
planning

`rating`

字段	类型	说明
`rating_type`	string	评分类型，可能为 `Max5`、`Percents` 或 `CustomMax`。
`value`	integer	当前评分值。数据可能小数。
`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	营业时间信息。
`current_status`	string	当前营业状态：`opened`、`closed`、`temporarily_closed`、`closed_forever`。

work_hours.timetable 按星期返回营业时段：

sunday
monday
tuesday
wednesday
thursday
friday
saturday

每天的值为时间段数组，每个时间段：

json

{
  "open": {
    "hour": 9,
    "minute": 0
  },
  "close": {
    "hour": 18,
    "minute": 0
  }
}

：

hour：24 小时制小时数。
minute：分钟数。
某天为 null 时，表示没有返回该天的营业时间。

`popular_times`

字段	类型	说明
`popular_times_by_days`	object	按星期划分的繁忙时段。
`sunday` 至 `saturday`	array	对应星期的繁忙时段数组。
`time`	object	时段时间， `hour` 和 `minute`。
`popular_index`	integer	繁忙指数，范围为 0–100。数值越高，表示该时段越繁忙。

`local_business_links`

用于描述搜索结果页中的商家互动：

字段	类型	说明
`type`	string	链接类型，可能为 `reservation`、`order` 或 `menu`。
`title`	string	链接标题或服务平台名称。
`url`	string	预约、下单或查看菜单的 URL。

`directory`

目录对象用于返回同一地址下的商家。

字段	类型	说明
`title`	string	目录标题，可能为 `At this place` 或 `Directory`。
`items`	array	目录中的商家数组。

目录项字段：

字段	类型	说明
`type`	string	固定为 `maps_search`。
`rank_group`	integer	同类型目录项中的组排名。
`rank_absolute`	integer	所有目录项中的绝对排名。
`domain`	string	商家域名。
`title`	string	商家名称。
`url`	string	商家绝对 URL。
`rating`	object	商家评分，结构同 `rating`。
`rating_distribution`	object	1–5 星评分分布。
`snippet`	string	商家附加信息。
`address`	string	商家地址。
`address_info`	object	地址拆分信息，结构同 `address_info`。
`place_id`	string	地点唯一标识。
`phone`	string	商家电话号码。
`main_image`	string	商家主图 URL。
`total_photos`	integer	图片总数。
`category`	string	商家类别。
`category_ids`	array	通用类别 ID。
`work_hours`	object	营业时间。
`feature_id`	string	结果项唯一标识。
`cid`	string	商家唯一标识。
`latitude`	float	纬度。
`longitude`	float	经度。
`is_claimed`	boolean	是否已由所有验证认领。
`local_justifications`	array	本地结果匹说明。
`is_directory_item`	boolean	是否属于目录项。
`price_level`	string	价格等级：`inexpensive`、`moderate`、`expensive`、`very_expensive`，无数据时为 `null`。
`hotel_rating`	integer	店星级，范围为 1–5，无数据时为 `null`。

`services`

服务数组中的每个对象：

字段	类型	说明
`category`	string	服务类别，例如 `Internet Marketing Service`。
`title`	string	服务名称。
`snippet`	string	商家提供的服务描述。
`price`	object	服务价格信息。

price 对象字段：

字段	类型	说明
`current`	float	当前价格。
`regular`	float	未折扣的常规价格。
`max_value`	float	未折扣价格范围的最大值。
`currency`	string	ISO 货币代码。
`is_price_range`	boolean	是否为价格区间。
`displayed_price`	string	商家资料中展示的原始价格文本。

响应示例

json

{
  "version": "0.1.20231117",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "10.2468 sec.",
  "cost": 0.0389,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "10.2468 sec.",
      "cost": 0.0389,
      "result_count": 1,
      "path": [
        "v3",
        "business_data",
        "google",
        "my_business_info",
        "live"
      ],
      "data": {
        "api": "business_data",
        "function": "my_business_info",
        "se": "google",
        "language_code": "en",
        "location_name": "New York,New York,United States",
        "keyword": "RustyBrick, Inc.",
        "se_type": "business_info",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "RustyBrick, Inc.",
          "location_code": 1023191,
          "language_code": "en",
          "item_types": [
            "google_business_info"
          ],
          "items_count": 1,
          "items": [
            {
              "type": "google_business_info",
              "title": "RustyBrick, Inc.",
              "cid": "2946633002421908862",
              "feature_id": "0x89c2e830ac1a4c3f:0x28e48b1a90ccf57e",
              "address": "250 W Nyack Rd #200, West Nyack, NY 10994",
              "address_info": {
                "borough": null,
                "address": "250 W Nyack Rd #200",
                "city": "West Nyack",
                "zip": "10994",
                "region": "New York",
                "country_code": "US"
              },
              "place_id": "ChIJP0warDDowokRfvXMkBqL5Cg",
              "phone": "+1877-467-8789",
              "url": "https://www.rustybrick.com/",
              "contact_url": null,
              "contributor_url": "https://maps.google.com/maps/contrib/104876075931666699163",
              "book_online_url": null,
              "domain": "www.rustybrick.com",
              "logo": "https://lh4.googleusercontent.com/example-logo",
              "main_image": "https://lh5.googleusercontent.com/example-image",
              "total_photos": 35,
              "snippet": "250 W Nyack Rd #200, West Nyack, NY 10994",
              "latitude": 41.097343,
              "longitude": -73.9934641,
              "is_claimed": true,
              "attributes": {
                "available_attributes": {
                  "from_the_business": {},
                  "service_options": {},
                  "accessibility": {},
                  "planning": {}
                },
                "unavailable_attributes": null
              },
              "place_topics": {
                "SEO": 4,
                "news": 3
              },
              "rating": {
                "rating_type": "Max5",
                "value": 4.7,
                "votes_count": 49,
                "rating_max": null
              },
              "hotel_rating": null,
              "price_level": null,
              "rating_distribution": {
                "1": 2,
                "2": 0,
                "3": 2,
                "4": 4,
                "5": 41
              },
              "people_also_search": [],
              "work_time": {
                "work_hours": {
                  "timetable": {
                    "sunday": null,
                    "monday": [],
                    "tuesday": [],
                    "wednesday": [],
                    "thursday": [],
                    "friday": [],
                    "saturday": null
                  },
                  "current_status": "opened"
                }
              },
              "popular_times": null,
              "local_business_links": null,
              "is_directory_item": false,
              "directory": null,
              "services": []
            }
          ]
        }
      ]
    }
  ]
}

错误处理

建议根据以下字段实现统一的异常处理：

顶层 status_code
顶层 status_message
任务级 tasks[].status_code
任务级 tasks[].status_message
tasks_error

完整响应状态码和错误信息请参考：

/v3/appendix/errors

当 status_code 不等于 20000 时，应记录任务 ID、请求参数和错误信息，并根据错误类型执行重试、参数修正或人工排查。

实用场景

核验本地商家资料：批量获取商家名称、地址、电话、网站和认领状态，发现本地搜索资料不一致问题并提升商家信息准确性。
监控本地 SEO 表现：定期采集商家评分、评论数量、评分分布和搜索结果排名，评估本地 SEO 优化效果。
分析竞争商家：通过 people_also_search、类别、价格等级和服务信息识别竞争对手，制定区域市场策略。
优化商家转化：提取预约、下单、菜单和链接，检查搜索结果中的转化路径是否完整并发现失效。
规划门店运营：分析营业状态、营业时间和繁忙时段，为门店排班、营销投放和到店服务安排提供依据。

设置 Google 商家信息实时任务 ​

计费与请求限制 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items 商家信息字段 ​

address_info ​

attributes ​

rating ​

rating_distribution ​

people_also_search ​

work_time ​

popular_times ​

local_business_links ​

directory ​

services ​

响应示例 ​

错误处理 ​

实用场景 ​