新闻搜索实时高级结果

POST /v3/serp/wp/news/live/advanced

接口概述

该接口用于实时获取指定在新闻搜索结果页中的高级 SERP 数据，支持按语言、地区、设备系统等条件抓取新闻结果，并返回结构化的结果项新闻条目、Top Stories 模块、发布时间、图片、XPath、像素位置等信息。

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

该接口适用于需要即时新闻 SERP 结果的场景。每次调用支持提交 1 个任务，每分钟最多可发起 2000 次 API 调用。

计费说明

该接口按请求计费。

每次请求都会产生费用
默认按每个最多 10 条结果的 SERP 计费
当 depth 大于 10 且搜索引擎返回 10 条结果时，可能产生额外费用
若设置的 depth 高于返回结果数，差额会自动退回到账户余额
若 keyword 中以下高级搜索运算符，任务费用会 放大 5 倍： allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site:
若 calculate_rectangles=true，任务费用会 放大 2 倍

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求体格式

所有 POST 数据使用 UTF-8 编码的 JSON，且请求体为 JSON 数组：

json

[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "android"
 }
]

主要参数

字段名	类型	说明
`keyword`	string	填。，最长支持 700 个字符。 `%##` 会被解码，`+` 会被解码为空格；如需在中保留 `%`，请写为 `%25`；如需保留 `+`，请写为 `%2B`。若高级搜索运算符，费用可能按 5 倍计算。不支持 `cache:` 查询参数，否则会返回校验错误。
`location_code`	integer	当未提供 `location_name` 或 `location_coordinate` 时为填。搜索地区代码。若使用该字段，则无需再传 `location_name` 或 `location_coordinate`。地区列表可通过 `/v3/serp/wp/locations` 获取。示例：`2840`
`language_code`	string	当未提供 `language_name` 时为填。搜索语言代码。若使用该字段，则无需再传 `language_name`。语言列表可通过 `/v3/serp/wp/languages` 获取。示例：`en`
`depth`	integer	可选。SERP 解析深度，即期望返回的结果数量。默认值：`10`；最大值：`200`

附加参数

字段名	类型	说明
`location_name`	string	当未提供 `location_code` 或 `location_coordinate` 时为填。搜索地区名。若使用该字段，则无需传 `location_code` 或 `location_coordinate`。可通过 `/v3/serp/wp/locations` 获取。示例：`London,England,United Kingdom`
`language_name`	string	当未提供 `language_code` 时为填。搜索语言名。若使用该字段，则无需传 `language_code`。可通过 `/v3/serp/wp/languages` 获取。示例：`English`
`os`	string	可选。设备操作系统。该接口提供桌面端结果。可选值：`windows`、`macos`。默认值：`windows`
`max_crawl_pages`	integer	可选。最多抓取的搜索结果页数。最大值：`100`。该参数与 `depth`合使用。
`search_param`	string	可选。附加搜索参数，用于扩展查询行为。
`calculate_rectangles`	boolean	可选。是否计算 SERP素的像素位置。像素位置表示结果片段相对屏幕左上角的距离。默认值：`false`。设置为 `true` 会导致费用翻倍。
`browser_screen_width`	integer	可选。浏览器屏幕宽度。在 `calculate_rectangles=true` 时生效。默认值：`1920`
`browser_screen_height`	integer	可选。浏览器屏幕高度。在 `calculate_rectangles=true` 时生效。默认值：`1080`
`browser_screen_resolution_ratio`	integer	可选。浏览器屏幕分辨率比例。在 `calculate_rectangles=true` 时生效。默认值：`1`
`url`	string	可选。直接传搜索 URL，本平台会自动解析为对应字段。该方式处理难度较高，且在 URL 中准确指定语言与地区，通常不建议使用。
`location_coordinate`	string	当未提供 `location_name` 或 `location_code` 时为填。GPS 坐标，格式为 `"latitude,longitude,radius"`。纬度和经度最多 7 位小数，`radius` 最小值 `199.9`（毫米），最大值 `199999`（毫米）。示例：`53.476225,-2.243572,200`
`se_domain`	string	可选。搜索引擎域名。通常本平台会根据地区和语言自动选择，也可手动指定，例如：`google.co.uk`、`google.com.au`、`google.de`

返回结果说明

接口返回 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	任务数组

任务级字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，取值范围通常为 `10000-60000`
`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	可直接访问的搜索结果页 URL，用于校验结果
`datetime`	string	结果获取时间，UTC 格式，例如：`2019-11-15 12:57:46 +00:00`
`spell`	object	搜索引擎自动纠错信息
`refinement_chips`	object	搜索细化建议模块
`includes_non_news_search_results`	boolean	是否除新闻结果外，还非新闻搜索结果
`item_types`	array	当前 SERP 中出现的结果类型，可能值：`top_stories`、`news_search`
`se_results_count`	integer	SERP 中结果总数
`items_count`	integer	`items` 数组中的结果数量
`items`	array	结构化 SERP素列表

`spell` 字段

当搜索引擎对进行了自动纠错时返回该对象。

字段名	类型	说明
`keyword`	string	自动纠错后的
`type`	string	自动纠错类型，可选值：`did_you_mean`、`showing_results_for`、`no_results_found_for`、`including_results_for`

`refinement_chips` 字段

字段名	类型	说明
`type`	string	固定为 `refinement_chips`
`xpath`	string	素的 XPath
`items`	array	细化建议项

`refinement_chips.items`素字段

字段名	类型	说明
`type`	string	固定为 `refinement_chips_element`
`title`	string	建议标题
`url`	string	带细化参数的搜索 URL
`domain`	string	SERP 中的域名
`options`	array	进一步细化选项

`options`素字段

字段名	类型	说明
`type`	string	固定为 `refinement_chips_option`
`title`	string	选项标题
`url`	string	带细化参数的搜索 URL
`domain`	string	SERP 中的域名

搜索结果说明

1）新闻搜索结果 `news_search`

字段名	类型	说明
`type`	string	固定为 `news_search`
`rank_group`	integer	同类型的组排名
`rank_absolute`	integer	SERP局绝对排名
`xpath`	string	素的 XPath
`domain`	string	结果域名
`title`	string	结果标题
`url`	string	结果链接
`image_url`	string	图片链接，可能指向原始资源或本平台缓存地址
`snippet`	string	摘要文本
`time_published`	string	新闻发布时间描述
`timestamp`	string	新闻发布时间，格式如：`2019-11-15 12:57:46 +00:00`
`rectangle`	object	像素位置与尺寸；若未启用 `calculate_rectangles` 则为 `null`

`rectangle` 字段

字段名	类型	说明
`x`	integer	左上角 x 坐标
`y`	integer	左上角 y 坐标
`width`	integer	素宽度（像素）
`height`	integer	素高度（像素）

2）头条新闻模块 `top_stories`

字段名	类型	说明
`type`	string	固定为 `top_stories`
`rank_group`	integer	同类型的组排名
`rank_absolute`	integer	SERP局绝对排名
`position`	string	素在 SERP 中的对齐位置；当前可见值：`left`
`xpath`	string	素的 XPath
`title`	string	模块标题
`items`	array	模块子项；若无则为 `null`
`rectangle`	object	像素位置与尺寸；若未启用 `calculate_rectangles` 则为 `null`

`top_stories.items` 子项字段

字段名	类型	说明
`type`	string	固定为 `top_stories_element`
`source`	string	新闻来源名称
`domain`	string	新闻来源域名
`title`	string	新闻标题
`date`	string	发布时间的相对描述，例如：`23 hours ago`
`amp_version`	boolean	是否提供 AMP 版本页面
`timestamp`	string	新闻发布时间，格式如：`2019-11-15 12:57:46 +00:00`
`url`	string	结果链接
`image_url`	string	图片链接，可能指向原始资源或本平台缓存地址
`rectangle`	object	像素位置与尺寸；若未启用 `calculate_rectangles` 则为 `null`

调用示例

curl

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/news/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "android",
 "calculate_rectangles": True
 }
]

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

TypeScript

typescript

import axios from "axios";

async function fetchNewsSerp {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/wp/news/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "android",
 calculate_rectangles: true
 }
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
 );

 console.log(response.data);
}

fetchNewsSerp.catch(console.error);

响应示例

json

{
 "version": "0.1.20220104",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "14.2469 sec.",
 "cost": 0.006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "news",
 "language_name": "English",
 "location_name": "United States",
 "keyword": "android",
 "calculate_rectangles": true,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 771000000,
 "items_count": 100,
 "items": [
 {
 "type": "news_search",
 "rank_group": 1,
 "rank_absolute": 1,
 "xpath": "/body/div/div/div/div/div/div/div/div/div/div",
 "domain": "www.eff.org",
 "title": "VICTORY: Google Releases “disable 2g” Feature for New Android Smartphones",
 "url": "https://www.eff.org/deeplinks/2022/01/victory-google-releases-disable-2g-feature-new-android-smartphones",
 "image_url": "https://api.seermartech.cn/cdn/i/01132007-1535-0139-0000-7b275022ce6d:0",
 "snippet": "Last year Google quietly pushed a new feature to its Android operating system allowing users to optionally disable 2G at the modem level in...",
 "time_published": null,
 "timestamp": "2022-01-12 22:07:51 +00:00",
 "rectangle": {
 "x": 180,
 "y": 182,
 "width": 652,
 "height": 178
 }
 },
 {
 "type": "top_stories",
 "rank_group": 1,
 "rank_absolute": 2,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/g-section-with-header",
 "title": "Nvidia's Shield TVs get Android 11 upgrade",
 "items": [],
 "rectangle": {
 "x": 180,
 "y": 376,
 "width": 652,
 "height": 325
 }
 },
 {
 "type": "news_search",
 "rank_group": 2,
 "rank_absolute": 3,
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/div",
 "domain": "www.cnet.com",
 "title": "Nvidia's GeForce Now service can stream Fortnite on iPhone and Android",
 "url": "https://www.cnet.com/tech/gaming/nvidias-geforce-now-service-can-stream-fortnite-on-iphone-and-android/",
 "image_url": "https://api.seermartech.cn/cdn/i/01132007-1535-0139-0000-7b275022ce6d:1",
 "snippet": "The game streaming service, offered by chipmaker Nvidia, has new touch controls to make it easier to play the game too.",
 "time_published": null,
 "timestamp": "2022-01-13 17:07:51 +00:00",
 "rectangle": {
 "x": 180,
 "y": 729,
 "width": 652,
 "height": 178
 }
 },
 {
 "type": "top_stories",
 "rank_group": 2,
 "rank_absolute": 4,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/g-section-with-header",
 "title": "News about Android",
 "items": [],
 "rectangle": {
 "x": 180,
 "y": 923,
 "width": 652,
 "height": 325
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理

建议在接时对通用状态码和任务状态码都建立异常处理机制。

顶层 status_code / status_message：表示整次请求是否成功
任务级 status_code / status_message：表示单个任务执行状态
错误码与通用信息请参考：/v3/appendix/errors

常见注意事项：

请求体是 JSON 数组 [{ ... }]
单次 Live 请求只能提交 1 个任务
cache: 参数不被支持，会直接触发校验错误
若使用 browser_screen_width、browser_screen_height、browser_screen_resolution_ratio，同时设置 calculate_rectangles=true
新闻搜索接口支持桌面端结果，os 可在 windows、macos 中选择

实用场景

监控品牌新闻：实时抓取品牌词或产品词的新闻 SERP，及时发现媒体报道、负面舆或竞品借势。
分析新闻版位结构：识别 top_stories 与普通 news_search 的分布，判断是否更容易触发新闻聚合模块。
跟踪地区化新闻差异：按不同 location_code 或 location_coordinate 获取结果，比较同一事件在不同国家或城市的新闻可见度。
评估媒体发布效果：抓取指定主题词的新闻结果排名、来源域名和发布时间，评估稿件是否核心新闻位。
研究 SERP 可视化布局：启用 calculate_rectangles 获取像素位置，分析新闻结果在首屏中的可见性与点击竞争强度。

新闻搜索实时高级结果 ​

接口概述 ​

计费说明 ​

请求体格式 ​

主要参数 ​

附加参数 ​

返回结果说明 ​

顶层字段 ​

任务级字段 ​

result 数组字段 ​

spell 字段 ​

refinement_chips 字段 ​

refinement_chips.items素字段 ​

options素字段 ​

搜索结果说明 ​

1）新闻搜索结果 news_search ​

rectangle 字段 ​

2）头条新闻模块 top_stories ​

top_stories.items 子项字段 ​

调用示例 ​

curl ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​