Google 本地搜索结果任务创建

POST /v3/serp/google/local_finder/task_post

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

/v3/serp/google/local_finder/task_post

用于创建 Google 本地搜索结果采集任务。接口根据指定的、地理位置、语言、设备等条件，获取本地搜索结果。

本接口支持普通和高优级两种执行优级。任务创建成功后，可以通过返回的任务 ID 查询结果，也可以 pingback_url 或 postback_url，在任务完成后接收通知。

> 每个任务默认按桌面端最多 20 条结果或移动端最多 10 条结果计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

请求体使用 UTF-8 编码的 JSON 格式。
每个 POST 请求最多 100 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
单次请求 100 个任务时，出部分将返回错误码 40006。
任务完成后，如果回调服务器在 10 秒未响应，连接将因时中断，任务会转移到任务就绪列表。

请求参数

主参数

字段	类型	填	说明
`keyword`	string	是	搜索，最长 700 个字符。请求中的编码会被解码，`+` 会被解码为空格。如果中需要使用 `%`，请传 `%25`；如果需要使用 `+`，请传 `%2B`。
`location_code`	integer	条件填	搜索位置编码。当未指定 `location_name` 或 `location_coordinate` 时填。使用此字段后，不应同时传另外两个位置字段。可通过 `/v3/serp/wp/locations` 获取位置编码列表。示例：`2840`。
`language_code`	string	条件填	搜索语言编码。当未指定 `language_name` 时填。使用此字段后，不应同时传 `language_name`。可通过 `/v3/serp/wp/languages` 获取语言编码列表。示例：`en`。
`depth`	integer	否	结果解析深度，即最多获取的结果数量。桌面端默认值为 `20`，最大值为 `500`；移动端默认值为 `10`，最大值为 `350`。
`priority`	integer	否	任务优级：`1` 表示普通优级，默认值；`2` 表示高优级。高优级任务会产生额外费用。
`device`	string	否	设备类型，可选值为 `desktop`、`mobile`，默认值为 `desktop`。
`pingback_url`	string	否	任务完成通知地址。任务完成后，本平台会向该地址发送 GET 请求。URL 中可使用 `$id` 和 `$tag` 占位符，平台发送请求时会替换为值。
`postback_url`	string	否	任务结果回调地址。任务完成后，本平台会向该地址发送 POST 请求，并以 gzip 格式压缩结果。URL 中可使用 `$id` 和 `$tag` 占位符。
`postback_data`	string	条件填	当指定 `postback_url` 时填，用于指定回调数据类型。可选值：`advanced`、`html`。

计费说明

桌面端每个 SERP 默认最多 20 条结果，移动端默认最多 10 条结果。
将 depth 设置为桌面端大于 20 或移动端大于 10 的值时，如果搜索引擎返回了更多结果，可能产生额外费用。
如果指定的 depth 高于返回结果数量，未使用部分的费用会自动退回账户余额。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

附加参数

字段	类型	填	说明
`location_name`	string	条件填	搜索位置的完整名称。当未指定 `location_code` 或 `location_coordinate` 时填。使用此字段后，不应同时传另外两个位置字段。示例：`London,England,United Kingdom`。
`language_name`	string	条件填	搜索语言的完整名称。当未指定 `language_code` 时填。示例：`English`。
`os`	string	否	设备操作系统。当 `device` 为 `desktop` 时，可选 `windows`、`macos`，默认值为 `windows`；当 `device` 为 `mobile` 时，可选 `android`、`ios`，默认值为 `android`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。可用于任务与结果。指定的值会原样出现在响应的 `data` 对象中。
`location_coordinate`	string	条件填	地理位置 GPS 坐标。当未指定 `location_name` 或 `location_code` 时填。格式为 `纬度,经度,缩放级别`，例如：`52.6178549,-155.352142,18z`。缩放级别可省略，默认使用 `9z`；纬度和经度最多保留 7 位小数；缩放级别范围为 `4z` 至 `18z`。
`min_rating`	number	否	最低评分过滤条件。桌面端可选值：`3.5`、`4`、`4.5`；移动端可选值：`2`、`2.5`、`3`、`3.5`、`4`、`4.5`。
`time_filter`	string	否	按营业时间过滤地点。可选值：`open_now`、`24_hours`、`$day_value`、`$day_value;$time_value`。星期值可使用 `monday` 至 `sunday`；小时值可使用 `00` 至 `23`。例如：`tuesday;18`。搜索引擎可能仍返回不符合该过滤条件的结果。

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

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/google/local_finder/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "keyword": "local nail services",
      "min_rating": 4.5,
      "time_filter": "monday"
    },
    {
      "language_name": "English",
      "location_name": "United States",
      "keyword": "local nail services",
      "min_rating": 4.5,
      "time_filter": "monday",
      "priority": 2,
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/google/local_finder/task_post"

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

payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "local nail services",
        "min_rating": 4.5,
        "time_filter": "monday",
    },
    {
        "language_name": "English",
        "location_name": "United States",
        "keyword": "local nail services",
        "min_rating": 4.5,
        "time_filter": "monday",
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    language_code: "en",
    location_code: 2840,
    keyword: "local nail services",
    min_rating: 4.5,
    time_filter: "monday",
  },
  {
    language_name: "English",
    location_name: "United States",
    keyword: "local nail services",
    min_rating: 4.5,
    time_filter: "monday",
    priority: 2,
    tag: "some_string_123",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/serp/google/local_finder/task_post",
    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	请求级状态码。
`status_message`	string	请求级状态信息。
`time`	string	请求执行耗时，单位为秒。
`cost`	number	本次请求的费用字段。扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。可使用该 ID 查询任务结果。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时，单位为秒。
`cost`	number	单个任务的费用字段。扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。任务创建接口成功时通常为 `0`。
`path`	array	结果路径信息。
`data`	object	创建任务时提交的参数，以及接口补的任务信息。
`result`	array \| null	任务结果数组。任务创建成功后通常为 `null`。

完整错误码可参考 /v3/appendix/errors。建议客户端对请求级错误、单任务错误、时和回调失败进行独立处理。

响应示例

json

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2539 sec.",
  "cost": 0.1,
  "tasks_count": 2,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "11141653-0696-0066-0000-fa25e0da658e",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0000 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "local_finder",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "local nail services",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    },
    {
      "id": "21141653-0696-0066-0000-fa25e0da658e",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0000 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "local_finder",
        "language_name": "English",
        "location_name": "United States",
        "keyword": "local nail services",
        "priority": 2,
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
        "tag": "some_string_123",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

实用场景

采集指定城市的本地搜索结果，评估门店在目标区域的本地搜索和竞争格局。
按评分和营业时间筛选商家，定位符合服务标准且在指定时间营业的潜在客户或竞品。
对比桌面端与移动端排名，识别不同设备上的本地搜索展示差异并优化本地 SEO。
批量监测多个和地区，建立门店、城市与服务词维度的本地排名追踪体系。
使用回调地址接收任务结果，减少轮询开销并及时触发排名报表或告警流程。

Google 本地搜索结果任务创建 ​

请求限制 ​

请求参数 ​

主参数 ​

计费说明 ​

附加参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应说明 ​

顶层字段 ​

任务字段 ​

响应示例 ​

实用场景 ​