实时 SERP 高级结果

GET /v3/appendix/errors

本接口用于实时获取指定、搜索引擎、语言和地理位置下的搜索结果页（SERP）。除自然结果和广告结果外，还会返回精选摘要、知识图谱、本地结果、购物、视频、问答、AI 概览等 SERP 特殊及详细字段。

请求方法与路径：

http

POST https://api.seermartech.cn/v3/serp/wp/organic/live/advanced

请求体使用 UTF-8 编码的 JSON 数组。每次请求只能 1 个任务；平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费说明

每个任务单独计费。
depth 默认获取 10 条结果；当搜索引擎返回 10 条结果时，设置更大的 depth 可能产生额外费用。
max_crawl_pages 按抓取页数计费，每页通常最多 10 条自然结果。
使用 load_async_ai_overview 或 calculate_rectangles 时会产生额外费用。
- load_async_ai_overview=true：参考价约 ¥0.0140 / 次。
- people_also_ask_click_depth：参考价约 ¥0.0011 / 次点击。
- calculate_rectangles=true：参考价约 ¥0.0140 / 次。
以下高级搜索操作符时，任务费用可能按 5 倍计算：allinanchor:、allintext:、allintitle:、allinurl:、cache:、define:、definition:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、site:。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

认证

请求头需使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

核心参数

参数	类型	填	说明
`keyword`	string	是	搜索，最长 700 个字符。`%XX` 和 `+` 会被解码 `+` 会转换为空格。如需传递字面量 `%`，请使用 `%25`；如需传递字面量 `+`，请使用 `%2B`。
`location_code`	integer	条件填	搜索位置编码。未提供 `location_name` 或 `location_coordinate` 时填。示例：`2840`。
`location_name`	string	条件填	搜索位置完整名称。未提供 `location_code` 或 `location_coordinate` 时填。示例：`London,England,United Kingdom`。
`location_coordinate`	string	条件填	GPS 位置，格式为 `纬度,经度,半径`。纬度和经度最多 7 位小数，半径范围为 `199-199999` 毫米。示例：`53.476225,-2.243572,200`。
`language_code`	string	否	搜索语言编码。提供后无需提供 `language_name`。示例：`en`。
`language_name`	string	否	搜索语言名称。提供后无需提供 `language_code`。示例：`English`。
`depth`	integer	否	抓取的 SERP 结果数量，默认 `10`，最大 `200`。
`device`	string	否	设备类型，可选 `desktop`、`mobile`，默认 `desktop`。
`os`	string	否	操作系统。桌面端可选 `windows`、`macos`，默认 `windows`；移动端可选 `android`、`ios`，默认 `android`。
`load_async_ai_overview`	boolean	否	是否加载异步生成的 AI 概览。默认 `false`。设置为 `true` 后，即使 AI 概览是异步加载，也会尝试获取。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

抓取控制参数

参数	类型	说明
`stop_crawl_on_match`	array	指定命中目标后停止抓取。最多 10 个目标，每个目标 `match_type` 和 `match_value`。响应将截至命中目标所在位置的 SERP 结果。
`match_type`	string	目标匹方式：`domain`（域名或子域名）、`with_subdomains`（主域名及子域名）、`wildcard`（通符模式）。
`match_value`	string	要匹的域名、子域名或通符值。域名不得协议头。示例：`example.com`、`/blog/post-*`。
`target_search_mode`	string	多目标匹模式在启用 `stop_crawl_on_match` 时生效。`all` 表示目标命中后停止，`any` 表示任意目标命中后停止，默认 `any`。
`find_targets_in`	array	指定在哪些 SERP素中查找目标。可选：`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`	array	指定不参与目标匹的 SERP素类型。不能与 `find_targets_in`含相同类型。
`max_crawl_pages`	integer	最多抓取的 SERP 页数，最大值为 `100`。该参数与 `depth`合使用。

搜索与结果处理参数

参数	类型	说明
`search_param`	string	附加搜索参数。以下参数不受支持，传后会自动移除：`lr`、`cr`、`as_qdr`、`as_sitesearch`、`as_occt`、`as_filetype`。
`url`	string	直接传搜索引擎查询 URL。系统会从 URL 中解析、语言和位置。在 URL 中指定准确的语言和位置，不建议作为常规调用方式。
`se_domain`	string	搜索引擎域名。平台通常根据位置和语言自动选择，也可手动指定，例如 `google.co.uk`、`google.com.au`、`google.de`。
`target`	string	限定目标域名、子域名或网页。不得 `https://` 和 `www.`，也可以使用 ``。示例：`example.com`、`example.com`、`example.com`、`example.com/example-page`。
`remove_from_url`	array	从返回结果 URL 中删除指定参数，最多 10 个。若同时指定 `target`，会在搜索前删除这些参数。
`group_organic_results`	boolean	是否将同域名的结果合并到父级自然结果中。`true` 为嵌套在 `related_result` 中，`false` 为单独的自然结果，默认 `true`。
`people_also_ask_click_depth`	integer	点击“用户还问了”的深度，范围 `1-4`，用于获取更多 `people_also_ask_element`。
`calculate_rectangles`	boolean	是否计算 SERP素的像素坐标和尺寸，默认 `false`。启用后返回 `rectangle` 对象。

浏览器尺寸参数

以下参数在 calculate_rectangles=true 时生效。

参数	类型	说明
`browser_screen_width`	integer	浏览器屏幕宽度，范围 `240-9999`。默认值：桌面端 `1920`，Android 移动端 `360`，iOS 移动端 `375`。
`browser_screen_height`	integer	浏览器屏幕高度，范围 `240-9999`。默认值：桌面端 `1080`，Android 移动端 `640`，iOS 移动端 `812`。
`browser_screen_resolution_ratio`	number	屏幕分辨率比例，范围 `0.5-3`。默认值：桌面端 `1`，移动端 `3`。

请求示例

cURL

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/organic/live/advanced"

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

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

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

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        "请求失败：{} {}".format(
            data.get("status_code"),
            data.get("status_message"),
        )
    )

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/wp/organic/live/advanced",
  [
    {
      language_code: "en",
      location_code: 2840,
      keyword: "albert einstein",
      device: "desktop",
      os: "windows",
      calculate_rectangles: true,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    response.data.status_code,
    response.data.status_message
  );
}

响应结构

接口返回 JSON 对象，顶层 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前接口版本。
`status_code`	integer	请求级状态码。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	请求级状态信息。
`time`	string	请求执行耗时，例如 `0.3059 sec.`。
`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	请求路径信息。
`data`	object	本次请求中提交的任务参数。
`result`	array	SERP 结果数组。

SERP 结果字段

字段	类型	说明
`keyword`	string	实搜索，已对 `%XX` 和 `+` 完成解码。
`type`	string	搜索引擎结果类型。
`se_domain`	string	实使用的搜索引擎域名。
`location_code`	integer	搜索位置编码。
`language_code`	string	搜索语言编码。
`check_url`	string	对应的搜索结果页 URL，可用于核验结果。
`datetime`	string	获取结果的 UTC 时间，格式为 `yyyy-mm-dd hh-mm-ss +00:00`。
`spell`	object	搜索引擎自动纠错信息。
`refinement_chips`	object	搜索细化选项。
`item_types`	array	当前 SERP 中的类型。
`se_results_count`	integer	SERP 中的结果总数。
`pages_count`	integer	实获取的 SERP 页数。
`items_count`	integer	`items` 数组中的数量。
`items`	array	SERP素数组。

item_types 可能以下值：

text

answer_box
app
carousel
multi_carousel
featured_snippet
google_flights
google_reviews
third_party_reviews
images
jobs
knowledge_graph
local_pack
hotels_pack
map
organic
paid
people_also_ask
related_searches
people_also_search
shopping
top_stories
twitter
video
events
recipes
top_sights
scholarly_articles
popular_products
questions_and_answers
find_results_on
stocks_box
commercial_units
local_services
google_hotels
math_solver
currency_box
product_considerations
short_videos
refine_products
perspectives
discussions_and_forums
compare_sites
ai_overview

SERP素通用字段

多数一级 SERP素以下字段：

字段	类型	说明
`type`	string	素类型。
`rank_group`	integer	同类型中的组排名。
`rank_absolute`	integer	所有 SERP素中的绝对排名。
`page`	integer	素所在的 SERP 页码。
`position`	string	素对齐方式，可为 `left` 或 `right`。
`xpath`	string	素在页面中的 XPath。
`title`	string	素标题。
`description`	string	素描述或摘要。
`url`	string	素对应 URL。
`domain`	string	素所属域名。
`source`	string	素信息来源。
`timestamp`	string	发布时间或索引时间，使用 UTC 格式。
`rectangle`	object/null	素在浏览器中的像素位置和尺寸。未启用 `calculate_rectangles` 时通常为 `null`。

`rectangle` 字段

字段	类型	说明
`x`	integer	素左上角的横坐标。
`y`	integer	素左上角的纵坐标。
`width`	integer	素宽度，单位为像素。
`height`	integer	素高度，单位为像素。

主要类型

`organic`：自然结果

常见字段：

字段	类型	说明
`domain`	string	自然结果域名。
`title`	string	结果标题。
`url`	string	结果 URL。
`cache_url`	string	缓存页面 URL。
`breadcrumb`	string	面屑路径。
`website_name`	string	网站名称。
`description`	string	结果描述。
`pre_snippet`	string	描述前附加。
`extended_snippet`	string	描述后附加。
`highlighted`	array	描述中加粗的。
`images`	array/null	结果中的图片。
`links`	array/null	站点链接。
`related_result`	array	同域名结果。
`rating`	object/null	评分信息。
`price`	object/null	价格信息。
`checks`	array/null	检测到的属性。
`amp_version`	boolean	是否存在 AMP 版本。

checks 可：

text

is_image
is_video
is_featured_snippet
amp_version
is_malicious
is_web_story
is_highly_cited

`paid`：付费结果

除通用字段外，还可能：

website_name：广告网站名称。
breadcrumb：广告面屑。
description：广告描述。
description_rows：扩展描述。
links：广告站点链接。
images：广告图片。
extra.ad_aclk：广告标识。
price：广告中的价格信息。
rating：广告评分。

`featured_snippet`：精选摘要

可能：

domain
title
featured_title
description
url
timestamp
images
table
rectangle

`answer_box`：答案框

可能：

text
links
rank_group
rank_absolute
page
position
xpath
rectangle

`knowledge_graph`：知识图谱

可能：

title
subtitle
description
card_id
url
image_url
logo_url
cid
items
link
rectangle

items 中可能出现以下类型：

text

knowledge_graph_images_item
knowledge_graph_list_item
knowledge_graph_ai_overview_item
knowledge_graph_description_item
knowledge_graph_row_item
knowledge_graph_carousel_item
knowledge_graph_part_item
knowledge_graph_expanded_item
knowledge_graph_shopping_item
knowledge_graph_hotels_booking_item

这些子可能 title、subtitle、text、url、domain、image_url、data_attrid、link、items、expanded_element、table 和 rectangle 等字段。

`local_pack`：本地结果

常见字段：

title
description
domain
phone
booking_url
url
is_paid
rating
cid
rectangle

cid 是本地商户的唯一标识，可用于后续获取该商户的评论数据。

`hotels_pack` 与 `google_hotels`：结果

hotels_pack 可能：

title
date_from
date_to
items
rectangle

条目可能：

title
description
hotel_identifier
domain
url
is_paid
price
rating
rectangle

google_hotels 主要返回：

hotel_identifier
url
cid
rank_group
rank_absolute
page
position
xpath
rectangle

`images`：图片结果

可能：

title
url
items
related_image_searches
rectangle

图片条目通常：

alt
url
image_url
type

`shopping` 与 `popular_products`：购物结果

购物条目可能：

title
url
domain
description
source
marketplace
marketplace_url
image_url
price
rating
product_identifiers
rectangle

product_identifiers 可能：

字段	说明
`product_id`	购物结果中的商品唯一标识。
`data_docid`	SERP 数据唯一标识。
`gid`	商品局标识。

`people_also_ask`：用户还问了

可能：

items
title
seed_question
expanded_element
rectangle

问答条目可能：

title
question_text
answer_text
source
domain
votes
url
images
table
timestamp

`related_searches` 与 `people_also_search`

related_searches.items：与当前查询的搜索词。
people_also_search.title：搜索模块标题。
people_also_search.items：热门。
两均可能排名、位置、XPath 和 rectangle。

`carousel` 与 `multi_carousel`

carousel 条目可能：

title
subtitle
image_url
rectangle

multi_carousel 可能：

items
multi_carousel_snippets
title
xpath
rectangle

`top_stories`、`video` 与 `short_videos`

新闻或视频条目可能：

title
source
domain
url
description 或 snippet
image_url
date
timestamp
amp_version
rectangle

视频条目还可能：

thumbnail
source
published 时间

`jobs`：职位结果

职位条目可能：

title
description
location
author
job_posted_time
timestamp
contract_type
salary
url
rectangle

`events`、`recipes` 与 `top_sights`

`events`

可能：

title
snippet
url
rectangle

`recipes`

可能：

title
url
domain
source
description
time
rating
rectangle

`top_sights`

可能：

title
url
description
rating
rectangle

`scholarly_articles`

可能：

title
url
author
description
items
rectangle

`google_reviews` 与 `third_party_reviews`

评论模块可能：

reviews_count
rating
place_id
feature
cid
title
url
rectangle

评分对象 rating 字段如下：

字段	类型	说明
`rating_type`	string	评分类型：`Max5`、`Percents` 或 `CustomMax`。
`value`	float	评分值。
`votes_count`	integer	评分数量。
`rating_max`	integer	评分最大值。

`local_services` 与 `commercial_units`

本地服务或商业单可能：

title
url
domain
description
source
price
rating
items
rectangle

`math_solver`

数学计算结果可能：

title
result
items
expanded_element
links
rectangle

expanded_element 可：

title
solution

`currency_box`

汇率结果可能：

value
converted_value
currency
converted_currency
timestamp
table
graph
rectangle

图表数据使用以下字段：

date：yyyy-mm-ddThh:mm:ss 格式。
value：对应时间点的汇率。
previous_items：前一时间段的汇率数据。

`stocks_box`

股票结果可能：

title
source
snippet
price
url
domain
table
graph
rectangle

股票价格可能存在延迟，使用时应以搜索结果页面展示的时间为准。

`questions_and_answers`

问答结果可能：

url
question_text
answer_text
source
domain
votes
rectangle

`find_results_on`

用于表示“在指定来源中查找结果”的模块，可能：

title
domain
url
source
items
rectangle

`product_considerations` 与 `refine_products`

`product_considerations`

可能：

title
items
rectangle

条目可能：

title
consideration_category
expanded_element
related_searches
about_this_result

`refine_products`

可能：

title
items
rectangle

细化商品条目可能：

title
image_url
keyword
refine_type
xpath
rectangle

`perspectives`、`discussions_and_forums` 与 `compare_sites`

`perspectives`

可能：

title
description
url
domain
date
source
timestamp
rectangle

`discussions_and_forums`

可能：

title
url
domain
source
description
timestamp
posts_count
rectangle

`compare_sites`

可能：

title
url
domain
image_url
source
items
rectangle

AI 概览字段

`ai_overview`

当 SERP 中存在 AI 概览时，结果可能：

type：固定为 ai_overview。
rank_group
rank_absolute
page
position
xpath
asynchronous_ai_overview
markdown
items
links
images
references
rectangle

asynchronous_ai_overview 的含义：

true：AI 概览为异步加载。
false：AI 概览来自缓存。

要获取异步 AI 概览，需要在请求中设置：

json

{
  "load_async_ai_overview": true
}

AI 概览子

items 中可能出现以下类型：

text

ai_overview_element
ai_overview_expanded_element
ai_overview_video_element
ai_overview_table_element
ai_overview_reference

`ai_overview_element`

可能：

position
title
text
markdown
links
images
references

`ai_overview_expanded_element`

可能：

position
title
text
components
references

组件 ai_overview_expanded_component 可能：

title
text
markdown
images
links
references

`ai_overview_video_element`

可能：

position
title
snippet
url
domain
image_url
source
date
timestamp

`ai_overview_table_element`

可能：

position
markdown
table
references

table 对象：

table_header：表头数组。
table_content：表格数组，每个数组代表一行。

`ai_overview_reference`

用于表示生成 AI 概览时引用的网页，可能：

source
domain
url
title
text

通用对象

价格对象 `price`

字段	类型	说明
`current`	float	当前价格。
`regular`	float	未折扣的常规价格。
`max_value`	float	价格区间中的最高价格。
`currency`	string	价格币种的 ISO 编码。
`is_price_range`	boolean	是否为价格区间。
`displayed_price`	string	SERP 中原始展示的价格文本。

图片对象

字段	类型	说明
`type`	string	通常为 `images_element`。
`alt`	string	图片替代文本。
`url`	string	图片页面 URL。
`image_url`	string	图片 URL。

链接对象

字段	类型	说明
`type`	string	通常为 `link_element`。
`title`	string	链接标题或锚文本。
`description`	string	链接描述。
`url`	string	链接 URL。
`domain`	string	链接所属域名。
`snippet`	string	链接旁的补文本。
`xpath`	string	链接 XPath。

已废弃字段

以下字段仍可能出现在响应中，但当前通常返回 null：

faq
about_this_result
related_image_searches

错误处理

建议同时检查：

HTTP 状态码；
顶层 status_code；
每个任务的 status_code；
tasks_error 是否大于 0；
status_message 中的错误信息。

完整错误码列表：

text

/v3/appendix/errors

实用场景

监控排名与 SERP 特殊：批量获取自然结果、广告、精选摘要、AI 概览和知识图谱，评估页面在搜索结果中的真实位置。
分析竞争对手搜索表现：通过 target、stop_crawl_on_match 和 find_targets_in 定位竞争域名，统计在自然结果、本地结果、广告和购物模块中的出现。
优化本地 SEO 策略：使用 location_code、location_coordinate、local_pack、local_services 和 google_reviews 分析不同城市的商户排名、评分和评论数量。
挖掘选题与搜索意图：提取 people_also_ask、related_searches、people_also_search、refine_products 和 discussions_and_forums，构建 FAQ、集群和产品细分。
评估 SERP 版位与视觉占位：启用 calculate_rectangles 获取像素坐标，测量精选摘要、广告、购物模块和 AI 概览在桌面端或移动端页面中的占位。

实时 SERP 高级结果 ​

计费说明 ​

认证 ​

请求参数 ​

核心参数 ​

抓取控制参数 ​

搜索与结果处理参数 ​

浏览器尺寸参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

SERP 结果字段 ​

SERP素通用字段 ​

rectangle 字段 ​

主要类型 ​

organic：自然结果 ​

paid：付费结果 ​

featured_snippet：精选摘要 ​

answer_box：答案框 ​

knowledge_graph：知识图谱 ​

local_pack：本地结果 ​

hotels_pack 与 google_hotels：结果 ​

images：图片结果 ​

shopping 与 popular_products：购物结果 ​

people_also_ask：用户还问了 ​

related_searches 与 people_also_search ​

carousel 与 multi_carousel ​

实时 SERP 高级结果

计费说明

认证

请求参数

核心参数

抓取控制参数

搜索与结果处理参数

浏览器尺寸参数

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

任务字段

SERP 结果字段

SERP素通用字段

`rectangle` 字段

主要类型

`organic`：自然结果

`paid`：付费结果

`featured_snippet`：精选摘要

`answer_box`：答案框

`knowledge_graph`：知识图谱

`local_pack`：本地结果

`hotels_pack` 与 `google_hotels`：结果

`images`：图片结果

`shopping` 与 `popular_products`：购物结果

`people_also_ask`：用户还问了

`related_searches` 与 `people_also_search`

`carousel` 与 `multi_carousel`