实时 SERP 采集（常规结果）

POST /v3/serp/wp/organic/live/regular

本接口用于实时获取指定关键词、搜索引擎、语言和地域下的搜索结果页数据。适合需要即查即得的 SERP 场景。

接口说明

请求方式：POST
接口地址：https://api.seermartech.cn/v3/serp/wp/organic/live/regular

说明：
每次请求都会产生费用。
参考价请结合平台计费规则估算，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
所有 POST 数据使用 UTF-8 编码的 JSON。
请求体格式为 JSON 数组：[{ ... }]
每次 Live SERP 请求支持 1 个任务。
频率上限为每分钟 2000 次 API 调用。

请求参数

以下为可用于创建任务的字段说明。

字段名	类型	说明
`url`	string	搜索查询的直达 URL，可选。可直接传完整查询链接，由本接口自动解析为所需字段。该方式处理难度较高，并且要求 URL 中精确的语言和地域信息，通常不建议优使用。示例：`https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8`
`keyword`	string	，填。最长支持 700 个字符。所有 `%##` 会被解码，字符 `+` 会被解码为空格。如需传 `%`，请写作 `%25`；如需传 `+`，请写作 `%2B`。
`location_name`	string	搜索地域名。当未提供 `location_code` 或 `location_coordinate` 时填。使用该字段时，无需再传 `location_code` 或 `location_coordinate`。地域列表可通过 `/v3/serp/wp/locations` 获取。示例：`London,England,United Kingdom`
`location_code`	integer	搜索地域编码。当未提供 `location_name` 或 `location_coordinate` 时填。使用该字段时，无需再传 `location_name` 或 `location_coordinate`。地域列表可通过 `/v3/serp/wp/locations` 获取。示例：`2840`
`location_coordinate`	string	地理坐标定位。当未提供 `location_name` 或 `location_code` 时填。格式为 `"latitude,longitude,radius"`。`latitude` 与 `longitude` 最多 7 位小数；`radius` 最小值 `199.9`（毫米），最大值 `199999`（毫米）。示例：`53.476225,-2.243572,200`
`language_name`	string	搜索语言名。当未提供 `language_code` 时填。使用该字段时，无需再传 `language_code`。语言列表可通过 `/v3/serp/wp/languages` 获取。示例：`English`
`language_code`	string	搜索语言编码。当未提供 `language_name` 时填。使用该字段时，无需再传 `language_name`。语言列表可通过 `/v3/serp/wp/languages` 获取。示例：`en`
`device`	string	设备类型，可选。可选值：`desktop`、`mobile`。默认：`desktop`
`os`	string	设备操作系统，可选。若 `device=desktop`，可选：`windows`、`macos`，默认 `windows`；若 `device=mobile`，可选：`android`、`ios`，默认 `android`
`se_domain`	string	搜索引擎域名，可选。系统会根据地域与语言自动选择合适域名，也可手动指定。示例：`au.search.yahoo.com`、`uk.search.yahoo.com`、`ca.search.yahoo.com`
`depth`	integer	解析深度，可选。表示需要返回的 SERP 结果数量。默认值：`6`；最大值：`700`。按抓取到的每个 SERP 计费。由于单个 SERP 可能少于 10 条结果，设置高于默认值可能导致额外费用，扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`max_crawl_pages`	integer	最大抓取页数，可选。表示最多抓取多少个搜索结果页。默认值：`1`；最大值：`100`。该参数与 `depth`合使用。
`target`	string	指定目标域名、子域名或网页，可选。域名或子域名请勿 `https://` 和 `www.`。启用后返回 `url` 字段的 SERP素。支持通符 ``。示例：`example.com`、`example.com`、`example.com`、`example.com`、`example.com/example-page`、`example.com/example-page`
`search_param`	string	搜索附加参数，可选。用于补搜索查询参数。
`stop_crawl_on_match`	array	命中目标后停止抓取的条件数组，可选。最多支持 10 个目标对象。若设置，响应中将返回直到匹到指定 `match_value` 为止的 SERP 结果（含该匹项）。在命中前，每抓取一个 SERP 都会计费。
`match_value`	string	`stop_crawl_on_match`部字段。设置匹的目标域名、子域名或通符模式。若使用 `stop_crawl_on_match` 则填。域名或子域名不能带协议头。示例：`"match_value": "example.com"`、`"match_value": "/blog/post-*"`
`match_type`	string	`stop_crawl_on_match`部字段。匹类型，若使用 `stop_crawl_on_match` 则填。可选值：`domain`（精确域名/子域名）、`with_subdomains`（主域名及子域名）、`wildcard`（通符模式）
`tag`	string	自定义任务标识，可选。最长 255 个字符。可用于在响应中业务侧任务。

请求体示例

json

[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "device": "desktop",
 "os": "windows"
 }
]

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/v2/live/regular" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/live/regular"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

response = requests.post(url, json=data, headers=headers)
print(response.json)

TypeScript

typescript

import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/wp/v2/live/regular",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein",
 },
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 console.log(response.data);
}

main.catch(console.error);

响应结构

接口返回 JSON 对象 tasks 数组，每个任务执行状态与结果数据。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码。完整错误码见 `/v3/appendix/errors`
`status_message`	string	通用状态信息。完整说明见 `/v3/appendix/errors`
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务结果数组

tasks 对象字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`，完整列表见 `/v3/appendix/errors`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	原样返回请求中提交的参数
`result`	array	结果数组

result 对象字段

字段名	类型	说明
`keyword`	string	请求中的。返回时 `%##` 会被解码，`+` 会被解码为空格
`type`	string	请求中的搜索类型
`se_domain`	string	请求中的搜索引擎域名
`location_code`	integer	请求中的地域编码
`language_code`	string	请求中的语言编码
`check_url`	string	搜索结果直达链接，可用于核验返回结果是否准确
`datetime`	string	结果采集时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`spell`	object	搜索引擎自动纠错信息；如果搜索词被修正，将返回修正后的及修正类型
`refinement_chips`	object	搜索细化建议，当前固定为 `null`
`item_types`	array	当前返回的 SERP 中出现的结果类型集合。可能：`featured_snippet`、`images`、`local_pack`、`hotels_pack`、`organic`、`paid`、`people_also_ask`、`related_searches`、`shopping`、`recipes`、`top_stories`、`video`、`ai_overview`。但本端点返回 `organic`、`paid`、`featured_snippet` 三类数据
`se_results_count`	integer	SERP 中的结果总量
`pages_count`	integer	实抓取到的结果页数量
`items_count`	integer	`items` 数组中的结果数量
`items`	array	SERP 结果项数组

items 中 organic素字段

字段名	类型	说明
`type`	string	素类型，固定为 `organic`
`rank_group`	integer	组排名。在相同 `type` 的结果中排序
`rank_absolute`	integer	SERP局绝对排名
`page`	integer	该结果所在的搜索结果页码
`domain`	string	结果域名
`title`	string	结果标题
`description`	string	结果摘要描述
`url`	string	结果链接
`breadcrumb`	string	面屑路径

响应示例

json

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3059 sec.",
 "cost": 0.003,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "wp",
 "se_type": "v2",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "flight ticket new york san francisco",
 "tag": "tag1",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 85600000,
 "pages_count": 1,
 "items_count": 96,
 "items": []
 }
 ]
 }
 ]
}

计费说明

本接口按请求计费。
响应中的 cost 字段单位为 USD。
若按示例响应估算，参考价约为：¥0.0480 / 次
当提高 depth、增加 max_crawl_pages，或使用 stop_crawl_on_match 触发多页抓取时，费用可能上升。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

错误处理

建议调用方基于以下层级进行错误处理：

检查顶层 status_code 是否为 20000
检查 tasks_error 是否为 0
遍历 tasks，检查每个任务的 status_code
若失败，请参考 /v3/appendix/errors 中的状态码定义进行重试、告警或降级处理

使用说明与注意事项

keyword 最长 700 字符，特殊字符会按 URL 编码规则解码。
location_name、location_code、location_coordinate 三至少提供一。
language_name、language_code 二至少提供一。
depth 与 max_crawl_pages 会影响最终抓取范围和费用。
使用 target 可聚焦某个域名、子域名或特定 URL 在 SERP 中的表现。
使用 stop_crawl_on_match 可在匹到指定站点后提前停止抓取，以控制数据量或加速定位结果。
如需获取返回 SERP 中富结果与更多 SERP 特性，应改用对应的 Advanced 类端点。

实用场景

监控排名：按、地域、语言实时抓取自然结果，快速确认页面在目标市场的排名变化。
定位竞品：通过 target 指定竞争对手域名，直接筛出在 SERP 中的出现位置与页面分布。
分析多地区差异：结合 location_code 或 location_coordinate 比较同一在不同城市或国家的结果差异，支持本地化 SEO 决策。
控制抓取成本：通过 stop_crawl_on_match 在命中目标站点后停止翻页，减少不的 SERP 抓取费用。
还原真实搜索环境：使用 device、os、language_code、se_domain 组合，模拟桌面端或移动端搜索场景，评估不同终端下的搜索可见性。

实时 SERP 采集（常规结果） ​

接口说明 ​

请求参数 ​

请求体示例 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 对象字段 ​

result 对象字段 ​

items 中 organic素字段 ​

响应示例 ​

计费说明 ​

错误处理 ​

使用说明与注意事项 ​

实用场景 ​

实时 SERP 采集（常规结果）

接口说明

请求参数

请求体示例

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

tasks 对象字段

result 对象字段

items 中 organic素字段

响应示例

计费说明

错误处理

使用说明与注意事项

实用场景