YouTube 自然搜索实时高级结果

POST /v3/serp/youtube/organic/live/advanced

接口说明

该接口用于实时获取 YouTube 搜索结果页中的自然搜索数据，返回 SERP 前若干区块中的详细结果。结果会根据所选地区和语言返回，适合用于监控视频、频道、播放列表等在 YouTube 搜索中的。

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

该接口为实时接口，每次请求都会直接返回结果。

计费与调用限制

本接口按请求计费。
参考价约 ¥0.0320 / 次
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
所有 POST 数据使用 JSON（UTF-8 编码）。
请求体为 JSON 数组格式：[{ ... }]
每分钟最多可发起 2000 次 API 调用。
每次 Live SERP 请求只能 1 个任务。

当设置 block_depth 大于 20 时：

账户将按每 最多 20 条 SERP 结果 为一个计费单位计费；
如果搜索引擎返回结果 20 条，可能产生额外费用；
如果指定的 block_depth 高于返回结果数量，差额部分会自动退回到账户余额。

请求参数

主要参数

字段名	类型	说明
`keyword`	string	填。搜索。最多支持 700 个字符。字段中的 `%##` 会被解码，字符 `+` 会被解码为空格。如果中需要保留 `%`，请写为 `%25`；如果需要保留 `+`，请写为 `%2B`。
`location_code`	integer	搜索地区代码。在未传 `location_name` 时填。传该字段时无需再传 `location_name`。可通过 `/v3/serp/youtube/locations` 获取可用地区代码。示例：`2840`
`language_code`	string	搜索语言代码。在未传 `language_name` 时填。传该字段时无需再传 `language_name`。可通过 `/v3/serp/youtube/languages` 获取可用语言代码。示例：`en`
`device`	string	可选。设备类型。可选值：`desktop`、`mobile`
`block_depth`	integer	可选。SERP 解析深度，即返回的结果区块数量。默认值：`20`；最大值：`700`

附加参数

字段名	类型	说明
`location_name`	string	搜索地区名。在未传 `location_code` 时填。传该字段时无需再传 `location_code`。可通过 `/v3/serp/youtube/locations` 获取可用地区名称。示例：`United States`
`language_name`	string	搜索语言名。在未传 `language_code` 时填。传该字段时无需再传 `language_code`。可通过 `/v3/serp/youtube/languages` 获取可用语言名称。示例：`English`
`os`	string	可选。设备操作系统。若 `device=desktop`，可选 `windows`、`macos`，默认 `windows`；若 `device=mobile`，可选 `android`、`ios`，默认 `android`
`tag`	string	可选。用户自定义任务标识，最大 255 个字符。可用于结果对账和任务识别；响应中的 `data` 对象会返回该值
`search_param`	string	可选。附加搜索参数。示例：`sp=EgIQAg%253D%253D`

请求示例

cURL

bash

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

Python

python

import requests

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

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

TypeScript

typescript

import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/youtube/organic/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "audi",
 },
 ],
 {
 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` 数组中返回错误的任务数量
`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	请求中的，返回时 `%##` 会被解码，`+` 会被解码为空格
`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 中出现的结果类型
`se_results_count`	integer	SERP 总结果数
`items_count`	integer	`items` 数组中的结果数量
`items`	array	搜索结果明细

`item_types` 可能值

youtube_channel
youtube_video
youtube_video_paid
youtube_playlist

结果项字段说明

`youtube_channel`

表示与搜索词的 YouTube 频道结果。

字段名	类型	说明
`type`	string	固定值：`youtube_channel`
`rank_group`	integer	同类型结果组排名
`rank_absolute`	integer	SERP部结果中的绝对排名
`block_rank`	integer	SERP 区块排名
`block_name`	string	SERP 区块名称，例如：`People also watched`
`channel_id`	string	频道 ID
`name`	string	频道名称
`url`	string	频道链接
`logo`	string	频道头像图片地址
`video_count`	integer	频道视频数量
`is_verified`	boolean	是否带有认证标识
`description`	string	频道描述
`highlighted`	array	描述中的高亮

`youtube_video`

表示普通 YouTube 视频结果。

字段名	类型	说明
`type`	string	固定值：`youtube_video`
`rank_group`	integer	同类型结果组排名
`rank_absolute`	integer	SERP部结果中的绝对排名
`block_rank`	integer	SERP 区块排名
`block_name`	string	SERP 区块名称，例如：`People also watched`
`title`	string	视频标题
`url`	string	视频链接
`video_id`	string	视频 ID
`thumbnail_url`	string	缩略图地址
`channel_id`	string	发布该视频的频道 ID
`channel_name`	string	发布该视频的频道名称
`channel_url`	string	发布该视频的频道链接
`channel_logo`	string	频道头像图片地址
`description`	string	视频描述
`highlighted`	array	描述中的高亮
`badges`	array	视频标签，例如：`New`、`CC`、`4K`
`is_live`	boolean	是否为直播
`is_shorts`	boolean	是否为 Shorts
`is_movie`	boolean	是否为电影
`views_count`	integer	观看次数
`publication_date`	string	发布时间描述
`timestamp`	string	结果发布时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`duration_time`	string	视频时长
`duration_time_seconds`	integer	视频时长（秒）

`youtube_video_paid`

表示 YouTube 付费视频类结果，字段与 youtube_video 基本一致。

字段名	类型	说明
`type`	string	固定值：`youtube_video_paid`
`rank_group`	integer	同类型结果组排名
`rank_absolute`	integer	SERP部结果中的绝对排名
`block_rank`	integer	SERP 区块排名
`block_name`	string	SERP 区块名称
`title`	string	视频标题
`url`	string	视频链接
`video_id`	string	视频 ID
`thumbnail_url`	string	缩略图地址
`channel_id`	string	发布该视频的频道 ID
`channel_name`	string	发布该视频的频道名称
`channel_url`	string	发布该视频的频道链接
`channel_logo`	string	频道头像图片地址
`description`	string	视频描述
`highlighted`	array	描述中的高亮
`badges`	array	视频标签
`is_live`	boolean	是否为直播
`is_shorts`	boolean	是否为 Shorts
`is_movie`	boolean	是否为电影
`views_count`	integer	观看次数
`publication_date`	string	发布时间描述
`timestamp`	string	结果发布时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`duration_time`	string	视频时长
`duration_time_seconds`	integer	视频时长（秒）

`youtube_playlist`

表示 YouTube 播放列表结果。

字段名	类型	说明
`type`	string	固定值：`youtube_playlist`
`rank_group`	integer	同类型结果组排名
`rank_absolute`	integer	SERP部结果中的绝对排名
`block_rank`	integer	SERP 区块排名
`block_name`	string	SERP 区块名称
`title`	string	播放列表标题
`url`	string	播放列表链接
`playlist_id`	string	播放列表 ID
`thumbnail_url`	string	缩略图地址
`channel_id`	string	发布该播放列表的频道 ID
`channel_name`	string	发布该播放列表的频道名称
`channel_url`	string	发布该播放列表的频道链接
`channel_logo`	string	频道头像图片地址
`videos_count`	integer	播放列表中的视频数量
`preview_videos`	array	预览视频信息数组
`preview_videos[].video_id`	string	视频 ID
`preview_videos[].title`	string	视频标题
`preview_videos[].url`	string	视频链接
`preview_videos[].duration_time`	string	视频时长
`preview_videos[].duration_time_seconds`	integer	视频时长（秒）

响应示例

json

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "11.0835 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "youtube",
 "se_type": "organic",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "audi",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 32629053,
 "items_count": 65,
 "items": [
 {
 "badges": [],
 "is_live": false,
 "is_shorts": false,
 "is_movie": null,
 "views_count": 1004,
 "publication_date": "43 minutes ago",
 "timestamp": "2022-12-30 14:12:23 +00:00",
 "duration_time": "23:26",
 "duration_time_seconds": 1406
 },
 {
 "type": "youtube_channel",
 "rank_group": 1,
 "rank_absolute": 9,
 "block_rank": 1,
 "block_name": null,
 "channel_id": "UCO5ujNeWRIwP4DbCZqZWcLw",
 "name": "Audi",
 "url": "https://www.youtube.com/@Audi",
 "logo": "https://yt3.googleusercontent.com/ytc/AMLnZu_iyn_apm6S6bi0P-nBUNil4mgAum9opQJGWeea=s176-c-k-c0x00ffffff-no-rj-mo",
 "video_count": 0,
 "is_verified": true,
 "description": "The official Audi YouTube Channel. From the beginning, advanced technology has been at the very heart of the Audi DNA.",
 "highlighted": []
 },
 {
 "type": "youtube_playlist",
 "rank_group": 2,
 "rank_absolute": 3,
 "block_rank": 3,
 "block_name": null,
 "title": "McQueen Car Assembly Surprise Soccer Ball | Street Vehicle with Learn Colors for Kids",
 "url": "https://www.youtube.com/playlist?list=PLeeA6TGUlbkZBi7TYks-CbPnFMsjjB5Be",
 "playlist_id": "PLeeA6TGUlbkZBi7TYks-CbPnFMsjjB5Be",
 "thumbnail_url": "https://i.ytimg.com/vi/i2mV0LApDTA/hqdefault.jpg?sqp=-oaymwEXCNACELwBSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLAbEK6cprhXavg6sjhL92EleU9O9w",
 "channel_id": "UCxaux2CGJvqAkGn5ohSQxdA",
 "channel_name": "Tech Editing info Master",
 "channel_url": "https://www.youtube.com/channel/UCxaux2CGJvqAkGn5ohSQxdA",
 "channel_logo": null,
 "videos_count": 81,
 "preview_videos": []
 }
 ]
 }
 ]
 }
 ]
}

错误处理

建议对以下字段建立统一的错误处理机制：

顶层 status_code / status_message
任务级 tasks[].status_code / tasks[].status_message

常见判断方式：

20000：请求成功
状态码：表示参数错误、认证失败、余额不足、频率限或服务执行异常等

完整错误码列表参考：/v3/appendix/errors

使用建议

优使用 location_code 与 language_code，便于程序化控制。
若需要更细的结果覆盖范围，可提高 block_depth，但需注意计费增长。
可结合 device 与 os 模拟不同终端下的 YouTube 搜索结果差异。
使用 tag 为请求附加业务标识，便于批量任务追踪与结果回写。
当需要校验抓取结果时，可使用返回的 check_url 进行人工复核。

实用场景

监控品牌词搜索结果，识别品牌频道、官方视频和第三方在 YouTube 搜索中的位置。
对比不同地区与语言下的 SERP 差异，评估视频的化覆盖效果和本地化优化空间。
跟踪竞品视频排名，分析竞品频道、单条视频和播放列表在目标下的占位策略。
识别 Shorts、直播与普通视频的展示分布，优化形式选择，提高目标覆盖率。
抽取播放列表与频道信息，用于搭建 YouTube SEO 数据看板，支持运营和投放决策。

YouTube 自然搜索实时高级结果 ​

接口说明 ​

计费与调用限制 ​

请求参数 ​

主要参数 ​

附加参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

item_types 可能值 ​

结果项字段说明 ​

youtube_channel ​

youtube_video ​

youtube_video_paid ​

youtube_playlist ​

响应示例 ​

错误处理 ​

使用建议 ​

实用场景 ​