设置 Google 扩展评价任务

POST /v3/business_data/google/extended_reviews/task_post

本接口使用 POST 方法，通过以下路径创建 Google 扩展评价采集任务：

POST https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_post

接口用于获取 Google 搜索结果页中“评价（Reviews）”模块的数据。返回 Google 用户评价，还可能 TripAdvisor、Yelp、Trustpilot 等可信来源的评价。结果会根据指定的地点和语言返回。

地点可通过以下接口查询：

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

计费说明

每返回最多 20 条评价计费一次。
例如，设置 "depth": 21 时，最多 40 条评价计费。
使用 keyword、cid 或 place_id 的计费倍率不同，详见参数说明。
priority: 2 高优级任务会产生额外费用。
示例响应中的 cost: 0.0045 美，按参考汇率折算约为 ¥0.0324。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有请求体使用 UTF-8 编码的 JSON 格式。每个 POST 请求的请求体是 JSON 数组，单次最多提交 100 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准；如果单次请求 100 个任务，出部分将返回错误码 40006。

任务创建成功后，可以通过返回的任务 id 获取结果。也可以在请求中指定 postback_url 或 pingback_url，任务完成后由本平台主动通知。

如果接收通知的服务器在 10 秒未响应，连接将因时中断，任务会转移到“任务就绪”列表。错误码和错误信息取决于接收服务器的。

请求参数

请求体为任务数组，每个数组代表一个任务。

参数	类型	填	说明
`keyword`	string	条件填	本地商户或经营场所名称。未指定 `cid` 和 `place_id` 时填。最多 700 个字符。
`cid`	string	条件填	Google 为商户实体分的唯一 ID。未指定 `keyword` 和 `place_id` 时填。
`place_id`	string	条件填	Google Maps 中商户实体的标识符。未指定 `keyword` 和 `cid` 时填。
`priority`	integer	否	任务优级：`1` 为普通优级，默认值；`2` 为高优级，需额外计费。
`location_name`	string	条件填	搜索引擎地点的完整名称。未指定 `location_code` 和 `location_coordinate` 时填。使用该字段后，无需再传另外两个地点参数。
`location_code`	integer	条件填	搜索引擎地点编码。未指定 `location_name` 和 `location_coordinate` 时填。
`location_coordinate`	string	条件填	地点 GPS 坐标，格式为 `latitude,longitude,radius`。未指定 `location_name` 和 `location_code` 时填。
`language_name`	string	条件填	搜索引擎语言完整名称。未指定 `language_code` 时填。
`language_code`	string	条件填	搜索引擎语言代码。未指定 `language_name` 时填。
`depth`	integer	否	解析深度，即希望获取的评价数量。默认值为 `20`，最大值为 `1000`。建议设置为 20 的倍数。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会出现在响应的 `data` 对象中，可用于任务和结果。
`postback_url`	string	否	任务完成后，本平台向该地址发送结果的 POST 请求，使用 gzip 压缩。
`pingback_url`	string	否	任务完成后，本平台向该地址发送 GET 请求进行通知。

`keyword` 使用规则

应体现本地商户或经营场所的名称。
% 编码会被解码，+ 会被解码为空格。
如果中需要使用 % 字符，请写成 %25。
如果以下搜索操作符，单个任务的费用将按标准费用的 5 倍计算：
allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site:

-含 cache: 的查询不受支持，将返回参数校验错误。

使用 keyword 创建 Google 评价任务时，按标准费率的 3 倍计费。

`cid`

Google 商户实体的唯一标识符，例如：

text

194604053573767737

使用 cid 创建任务时，按标准费率的 2 倍计费。

`place_id`

Google Maps 中商户实体的标识符，例如：

text

GhIJQWDl0CIeQUARxks3icF8U8A

使用 place_id 创建任务时，按标准费率的 2 倍计费。

地点参数

location_name、location_code 和 location_coordinate 三只能选择一。

`location_name`

地点完整名称示例：

text

London,England,United Kingdom

可通过以下接口获取可用地点及名称：

GET /v3/business_data/google/locations

`location_code`

地点编码示例：

text

可通过以下接口获取可用地点及编码：

GET /v3/business_data/google/locations

`location_coordinate`

格式：

text

latitude,longitude,radius

要求：

纬度和经度最多支持 7 位小数。
radius 最小值为 199.9。

示例：

text

53.476225,-2.243572,200

语言参数

language_name 和 language_code 二只能选择一。

`language_name`

语言名称示例：

text

English

可通过以下接口获取可用语言及名称：

GET /v3/business_data/google/languages

`language_code`

语言代码示例：

text

en

可通过以下接口获取可用语言代码：

GET /v3/business_data/google/languages

`depth`

表示希望解析的评价数量。
默认值：20
最大值：1000
建议设置为 20 的倍数，因为系统通常按每批 20 条评价进行处理。
设置 20 的值后，如果搜索引擎返回更多评价，可能产生额外费用。
例如，depth: 21 将按最多 40 条评价计费。

`postback_url` 和 `pingback_url`

可以使用以下变量：

$id：任务 ID
$tag：经过 URL 编码的任务标签

示例：

text

https://your-server.com/postbackscript?id=$id&tag=$tag

text

https://your-server.com/pingscript?id=$id&tag=$tag

URL 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "London,England,United Kingdom",
      "language_name": "English",
      "keyword": "hedonism wines"
    },
    {
      "location_name": "London,England,United Kingdom",
      "language_name": "English",
      "keyword": "hedonism wines",
      "depth": 40,
      "priority": 2,
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "location_name": "London,England,United Kingdom",
      "language_name": "English",
      "keyword": "hedonism wines",
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

TypeScript

typescript

import axios from "axios";

const taskData = [
  {
    location_name: "London,England,United Kingdom",
    language_name: "English",
    keyword: "hedonism wines",
  },
  {
    location_name: "London,England,United Kingdom",
    language_name: "English",
    keyword: "hedonism wines",
    depth: 40,
    priority: 2,
    tag: "some_string_123",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_post",
    taskData,
    {
      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);
  });

Python

python

import requests

url = "https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_post"

task_data = [
    {
        "location_name": "London,England,United Kingdom",
        "language_name": "English",
        "keyword": "hedonism wines",
    },
    {
        "location_name": "London,England,United Kingdom",
        "language_name": "English",
        "keyword": "hedonism wines",
        "depth": 60,
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
    {
        "location_name": "London,England,United Kingdom",
        "language_name": "English",
        "keyword": "hedonism wines",
        "postback_url": "https://your-server.com/postbackscript",
    },
]

response = requests.post(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json=task_data,
)

result = response.json()

if result.get("status_code") == 20000:
    print("任务创建成功：", result)
else:
    print(
        "任务创建失败。错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_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	已创建任务列表。

`tasks`素字段

字段	类型	说明
`id`	string	任务唯一标识符，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量。创建任务时通常为 `0`。
`path`	array	请求 URL 路径信息。
`data`	object	创建任务时提交的参数及系统补参数。
`result`	array/null	任务结果。任务创建接口返回时为 `null`，需通过任务结果接口获取评价数据。

完整错误码请参考本平台错误码文档。

响应示例

json

{
  "version": "0.1.20241028",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0681 sec.",
  "cost": 0.0045,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "76543210-1234-5678-9012-345678901234",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0123 sec.",
      "cost": 0.0045,
      "result_count": 0,
      "path": [
        "v3",
        "business_data",
        "google",
        "extended_reviews",
        "task_post"
      ],
      "data": {
        "api": "business_data",
        "function": "extended_reviews",
        "location_name": "London,England,United Kingdom",
        "language_name": "english",
        "cid": "17626775537598922320",
        "se_type": "extended_reviews",
        "se": "google",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

实用场景

采集本地商户评价，批量获取指定门店的 Google 及第三方平台评价，为口碑分析和门店运营提供数据。
监测竞争对手口碑，按商户名称、cid 或 place_id 定期创建任务，比较竞品评价数量与来源变化。
分析地点和语言差异，针对不同国家、城市和语言创建任务，评估本地搜索环境中的用户反馈。
构建评价舆看板，结合 tag、postback_url 或 pingback_url 自动任务结果，降低批量数据采集的处理成本。
评估评价覆盖规模，通过调整 depth 获取不同数量的评价，支持门店排名、服务质量和品牌声誉研究。

设置 Google 扩展评价任务 ​

计费说明 ​

请求参数 ​

keyword 使用规则 ​

cid ​

place_id ​

地点参数 ​

location_name ​

location_code ​

location_coordinate ​

语言参数 ​

language_name ​

language_code ​

depth ​

postback_url 和 pingback_url ​

请求示例 ​

cURL ​

TypeScript ​

Python ​

响应说明 ​

tasks素字段 ​

响应示例 ​

实用场景 ​

设置 Google 扩展评价任务

计费说明

请求参数

`keyword` 使用规则

`cid`

`place_id`

地点参数

`location_name`

`location_code`

`location_coordinate`

语言参数

`language_name`

`language_code`

`depth`

`postback_url` 和 `pingback_url`

请求示例

cURL

TypeScript

Python

响应说明

`tasks`素字段

响应示例

实用场景