SeerMarTech API 文档

主题

SERP Google V2 创建任务 ​

本接口用于创建 Google V2 SERP 抓取任务。

请求方法与路径：

text
POST https://api.seermartech.cn/v3/serp/wp/v2/task_post

接口默认返回搜索结果页前 10 条结果。结果会根据指定的搜索位置和语言生成。任务支持普通和高优级两种执行优级。

计费说明 ​

  • 在成功创建任务时计费。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • depth过 10 时，可能抓取的结果页增加费用。
  • 使用高优级任务会产生额外费用。
  • 启用 load_async_ai_overview 时，参考价约 ¥0.0043 / 次。
  • people_also_ask_click_depth 每次点击的参考价约 ¥0.0011。
  • 启用 calculate_rectangles 时，参考价约 ¥0.0043 / 次。
  • 以上均为人民币参考价，扣费以响应头为准。

请求限制 ​

  • 请求体使用 UTF-8 编码的 JSON。
  • 请求体格式为 JSON 数组：[{ ... }]。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 单次请求最多 100 个任务。 -出 100 个任务的部分会返回错误码 40006。
  • 创建任务后，可通过响应中的任务 id 查询结果。
  • 也可以通过 pingback_url 或 postback_url 接收任务完成通知。
  • 如果回调服务器在 10 秒未响应，连接会因时中断，任务将转“任务就绪”列表。

请求参数 ​

主要参数 ​

参数类型填说明
keywordstring是搜索，最多 700 个字符。% 和 + 等字符会被解码：如需使用 %，请传 %25；如需使用 +，请传 %2B。如果 allinanchor:、allintext:、allintitle:、allinurl:、cache:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、site: 等高级搜索操作符，单任务费用将乘以 5。
location_codeinteger条件填搜索位置代码。未指定 location_name 或 location_coordinate 时填。使用此参数后，无需再传另外两个位置参数。可通过位置列表接口获取：/v3/serp/google/locations。示例：2840。
language_codestring条件填搜索语言代码。未指定 language_name 时填。使用此参数后，无需再传 language_name。可通过语言列表接口获取：/v3/serp/google/languages。示例：en。
depthinteger否抓取深度，即 SERP 结果数量。默认值为 10，最大值为 700。每个最多 10 条结果的 SERP 会单独计费。
devicestring否设备类型，可选：desktop、mobile。默认值：desktop。
load_async_ai_overviewboolean否是否加载异步生成的 AI Overview。设为 true 时，即使 AI Overview 为异步加载，也会尝试获取；设为 false 时返回缓存中的 AI Overview。默认值：false。
pingback_urlstring否任务完成通知地址。任务完成后，本平台会向该地址发送 GET 请求。URL 中可使用 $id 和 $tag 占位符，系统会替换为任务 ID 和 URL 编码后的标签值。特殊字符会进行 URL 编码，例如 # 会编码为 %23。
postback_urlstring否任务结果回调地址。任务完成后，本平台会向该地址发送 POST 请求，并以 gzip 格式压缩结果。URL 中可使用 $id 和 $tag 占位符。
postback_datastring条件填当指定 postback_url 时填，用于指定发送到回调服务器的数据类型。可选：regular、advanced、html。

附加参数 ​

参数类型填说明
priorityinteger否任务优级：1 为普通优级，默认值；2 为高优级。高优级会产生额外费用。
location_namestring条件填搜索位置的完整名称。未指定 location_code 或 location_coordinate 时填。示例：London,England,United Kingdom。
location_coordinatestring条件填GPS 坐标，格式为 "纬度,经度,半径"。纬度和经度最多 7 位小数；半径最小值为 199 米，最大值为 199999 米。示例：53.476225,-2.243572,200。
language_namestring条件填搜索语言的完整名称。未指定 language_code 时填。示例：English。
tagstring否自定义任务标识，最多 255 个字符。可用于任务与结果，响应 data 对象中会返回该值。
osstring否设备操作系统。device 为 desktop 时可选：windows、macos，默认值为 windows；device 为 mobile 时可选：android、ios，默认值为 android。
stop_crawl_on_matcharray否用于提前终止抓取的目标数组，最多 10 个目标对象。每个对象 match_type 和 match_value。满足条件后，响应会截至匹结果为止的 SERP 数据。系统会抓取的 SERP 数量计费。
match_typestring条件填stop_crawl_on_match 中的匹类型。可选：domain（指定域名或子域名）、with_subdomains（主域名及子域名）、wildcard（通符模式）。
match_valuestring条件填要匹的域名、子域名或通符值。域名或子域名不得协议头。示例：example.com、/blog/post-*。
max_crawl_pagesinteger否最多抓取的搜索结果页数，最大值为 100。每抓取一页都会计费，每页 10 条自然搜索结果。该参数与 depth合使用。
search_paramstring否搜索查询的附加参数。不支持 lr、cr、as_qdr、as_sitesearch、as_occt、as_filetype，这些参数会被自动移除。
remove_from_urlarray否从结果 URL 中移除指定参数，最多可指定 10 个参数。
expand_ai_overviewboolean否是否展开 AI Overview。默认值：false。适用于 html 类型任务结果。
people_also_ask_click_depthinteger否对 people_also_ask素执行点击并获取更多 people_also_ask_element 的深度，可选范围为 1 至 4。每次点击都会产生额外费用；如果目标不存在，或点击次数少于指定值，未产生的额外费用会退回账户余额。
group_organic_resultsboolean否是否将结果作为父级自然结果的摘要返回。true 时，related_result 作为父级自然结果摘要返回；false 时，作为独立自然结果返回。默认值：true。
calculate_rectanglesboolean否是否计算高级结果中的像素排名。像素排名表示结果摘要与屏幕左上角之间的距离。默认值：false。启用后会产生额外费用。
browser_screen_widthinteger否浏览器屏幕宽度，用于计算特定设备的像素排名。取值范围：240-9999。默认值：桌面端 1920，Android 移动端 360，iOS 移动端 375。需同时将 calculate_rectangles 设为 true。
browser_screen_heightinteger否浏览器屏幕高度，用于计算特定设备的像素排名。取值范围：240-9999。默认值：桌面端 1080，Android 移动端 640，iOS 移动端 812。需同时将 calculate_rectangles 设为 true。
browser_screen_resolution_ratiointeger否浏览器屏幕分辨率比例，用于计算特定设备的像素排名。取值范围：0.5-3。默认值：桌面端 1，Android 移动端 3，iOS 移动端 3。需同时将 calculate_rectangles 设为 true。
urlstring否搜索查询的完整 URL。本平台会从 URL 中解析、语言和位置等参数。该方式处理复杂，且要求 URL 中准确的语言和位置信息，通常不建议使用。URL 中不支持 lr、cr、as_qdr、as_sitesearch、as_occt、as_filetype，这些参数会被自动移除。
target_search_modestring否多个目标的匹模式。在启用 stop_crawl_on_match 时生效。all 表示所有目标均找到后停止；any 表示任意一个目标找到后停止。默认值：any。
find_targets_inarray否指定在哪些 SERP素中查找目标。在启用 stop_crawl_on_match 时生效。未指定时，会检查所有 url 和 domain 字段的一级。可选值：organic、paid、local_pack、featured_snippet、events、google_flights、images、jobs、knowledge_graph、local_service、map、scholarly_articles、third_party_reviews、twitter。不能与 ignore_targets_in含相同类型。
ignore_targets_inarray否指定查找目标时需要排除的 SERP素类型。在启用 stop_crawl_on_match 时生效。可选值同 find_targets_in，且不能与 find_targets_in含相同类型。
se_domainstring否搜索引擎域名。本平台通常会根据位置和语言自动选择，也可以手动指定，例如 google.co.uk、google.com.au、google.de。

stop_crawl_on_match 示例 ​

json
{
  "stop_crawl_on_match": [
    {
      "match_type": "domain",
      "match_value": "example.com"
    },
    {
      "match_type": "wildcard",
      "match_value": "/blog/post-*"
    }
  ],
  "target_search_mode": "any",
  "find_targets_in": ["organic"]
}

请求示例 ​

curl ​

bash
curl --location --request POST \
  'https://api.seermartech.cn/v3/serp/wp/v2/task_post' \
  --header 'Authorization: Bearer smt_live_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "keyword": "albert einstein"
    },
    {
      "language_name": "English",
      "location_name": "United States",
      "keyword": "albert einstein",
      "priority": 2,
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
      "postback_data": "html",
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/task_post"

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

payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
    },
    {
        "language_name": "English",
        "location_name": "United States",
        "keyword": "albert einstein",
        "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, timeout=30)
response.raise_for_status()

result = response.json()
if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    language_code: "en",
    location_code: 2840,
    keyword: "albert einstein",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/serp/wp/v2/task_post",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应说明 ​

接口返回 tasks 数组的 JSON 数据。创建任务成功后，单个任务的 result 通常为 null，后续需要使用任务 ID 获取结果，或回调通知。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求整体状态码。完整错误码请参考错误码文档。
status_messagestring请求整体状态信息。
timestring请求处理耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray已创建任务的信息数组。

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常范围为 10000-60000。
status_messagestring任务状态信息。
timestring任务处理耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的结果数量。创建任务时通常为 0。
patharray结果路径信息。
dataobject创建任务时提交的参数，以及系统补的接口、设备和操作系统信息。
resultarray任务结果。创建任务成功后通常为 null。

响应示例 ​

json
{
  "version": "0.1.20200129",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0818 sec.",
  "cost": 0.0324,
  "tasks_count": 3,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01291721-1535-0066-0000-1e7a8bf7302c",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0048 sec.",
      "cost": 0.0108,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "wp",
        "se_type": "v2",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    },
    {
      "id": "01291721-1535-0066-0000-2e7a8bf7302c",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0050 sec.",
      "cost": 0.0108,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "wp",
        "se_type": "v2",
        "language_name": "English",
        "location_name": "United States",
        "keyword": "albert einstein",
        "priority": 2,
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
        "tag": "some_string_123",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    },
    {
      "id": "01291721-1535-0066-0000-ed3110168d43",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0040 sec.",
      "cost": 0.0108,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "wp",
        "se_type": "v2",
        "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
        "postback_data": "html",
        "postback_url": "https://your-server.com/postbackscript",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

状态码与错误处理 ​

  • 20000：请求成功。
  • 20100：任务创建成功。
  • 40006：单次请求提交的任务数量 100 个。
  • 状态码：表示请求或任务处理异常，请根据 status_code 和 status_message 进行处理。

建议客户端同时处理 HTTP 异常、顶层状态码异常和单个任务状态码异常，因部分任务失败而影响整批任务的处理。

实用场景 ​

  • 批量监控排名：按国家、城市、语言和设备批量创建 SERP 任务，持续跟踪目标的自然排名变化。
  • 对比桌面端与移动端结果：分别提交 desktop 和 mobile 任务，识别移动端与桌面端搜索结果差异，优化设备专项 SEO 策略。
  • 监测竞争对手：使用 stop_crawl_on_match、find_targets_in 检查竞争对手域名是否出现在自然结果、广告位或精选摘要中，降低无效抓取成本。
  • 分析本地搜索表现：通过 location_code、location_name 或 location_coordinate 指定精确区域，评估门店和本地服务页面在不同城市的搜索可见度。
  • 获取 AI Overview 与 SERP 像素位置：启用 load_async_ai_overview、expand_ai_overview 或 calculate_rectangles，分析 AI 摘要和 SERP素的展示位置及品牌。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API