YouTube 自然搜索 API 概览

YouTube 自然搜索 API 用于获取 YouTube 搜索结果页（SERP）中的顶部自然搜索结果。该能力基于 /v3/serp/youtube/organic/ 容路径提供，可按、语言和地理位置返回对应的 YouTube 搜索结果。

本接口会尽可能模拟指定位置下的搜索环境，使返回结果与任务创建时该地区、语言及对应的搜索结果保持一致。可通过响应中的 check_url 在浏览器无痕模式下访问并核验结果性。

> 系统不会应用用户登录状态、搜索历史、个性化偏好等因素，因此返回的是去个性化的搜索结果。

支持的设备与操作系统

创建任务时可指定以下设备类型及操作系统：

设备类型	支持的操作系统
mobile	ios、android
desktop	windows、macos

排名字段说明

SERP 结果中使用以下字段表示排名：

字段	说明
rank_group	结果在所属结果分组中的排名。例如自然结果、视频结果或结果区块的排序位置。
rank_absolute	结果在整个搜索结果页中的绝对排名。

rank_group 适合分析同类结果之间的竞争位置，rank_absolute 则适合衡量结果在完整页面中的整体位置。

可用功能

YouTube 自然搜索实时高级查询

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

实时高级查询接口会立即返回指定、搜索引擎、语言和位置对应的搜索结果，最多可获取前 20 个结果区块的数据。

该接口适用于需要同步获取结果的场景，例如用户在产品界面中即时发起查询、实时监控热点视频排名等。

获取方式

YouTube 自然搜索结果支持标准任务模式和实时模式。

标准任务模式

标准模式需要创建任务，再获取任务结果：

1. 使用 POST /v3/serp/youtube/organic/task_post/ 创建搜索任务；
2. 等任务完成；
3. 使用 GET /v3/serp/youtube/organic/task_get/advanced/ 获取结果。

该方式适合批量采集、异步数据处理和对时效性要求不高的场景，通常更好的成本效率。

创建任务时还可指定以下回调字段：

字段	说明
pingback_url	任务完成后向指定地址发送完成通知。收到通知后，您可通过任务获取接口拉取结果。
postback_url	任务完成后将结果直接推送至指定地址。使用该字段时，结果获取支持 advanced 数据格式。

如果一次提交多个任务，可按以下方式批量处理：

1. 调用 GET /v3/serp/youtube/organic/tasks_ready/ 获取已完成任务的 id 列表；
2. 针对每个任务 ID，调用 GET /v3/serp/youtube/organic/task_get/advanced/ 获取详细结果。

实时模式

实时模式使用以下接口：

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

该模式会在单次请求中同步完成搜索并返回结果，无需分别调用任务创建和任务获取接口。适用于对响应速度要求较高的业务，但相较标准模式成本更高。

请求频率限制

接口默认支持以下调用限制：

限制项	默认限制
平台限流以认证说明中的 30/60/120 次/分钟规则为准
单次 POST 请求中的任务数	最多 100 个任务

批量处理大量时，建议将任务分批提交，并通过 tasks_ready 接口按完成状态拉取结果。

优级与计费说明

实时模式会即时返回数据，因此通常为成本最高的调用方式。

标准任务模式支持两种执行优级：

1. normal：普通优级，适合常规异步采集任务；
2. high：高优级，适合需要更快完成的任务。

block_depth 对费用的影响

提高 block_depth 会增加任务费用。系统按默认结果区块深度的倍数计费。

例如，默认 block_depth 为 20：

• 设置 block_depth: 20：按 20 个结果计费；
• 设置 block_depth: 30：按两个 20 结果区间计费，即按 40 个结果计费。

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

认证方式

所有请求均需在请求头中携带 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

接口

接口	用途
POST /v3/serp/youtube/organic/task_post/	创建异步 YouTube 自然搜索任务。
GET /v3/serp/youtube/organic/task_get/advanced/	获取指定已完成任务的高级搜索结果。
GET /v3/serp/youtube/organic/tasks_ready/	获取已完成任务列表。
POST /v3/serp/youtube/organic/live/advanced/	实时获取 YouTube 自然搜索高级结果。
/v3/serp/youtube/languages/	获取可用语言列表。
/v3/serp/youtube/locations/	获取可用地理位置列表。

实用场景

• 监控视频排名：定期查询品牌词、产品词或行业词在 YouTube 中的自然排名，评估视频 SEO 优化效果。
• 挖掘竞品策略：分析目标下排名靠前的视频标题、频道和形式，识别竞品选题与发布策略。
• 评估区域化搜索表现：按国家、城市和语言采集搜索结果，比较同一在不同目标市场中的竞争。
• 发现视频机会：通过长尾的顶部结果判断供给密度，筛选竞争较低且搜索需求的视频选题。
• 构建视频搜索监控看板：结合标准任务模式批量追踪大量，持续沉淀排名变化、频道和趋势数据。