SeerMarTech API 文档

主题

获取 YouTube 自然搜索高级结果（按任务 ID） ​

接口说明 ​

用于根据任务 ID 获取 YouTube 自然搜索（Organic）高级结果。

请求方式： GET请求地址： https://api.seermartech.cn/v3/serp/youtube/organic/task_get/advanced/$id

你在创建任务后，只会在创建任务时产生扣费；任务结果在随后 30 天可重复获取。

参考价： 结果获取本身不重复计费，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数 ​

字段名类型说明
idstring任务唯一标识，UUID 格式。可在任务创建后的 30 天随时用来获取结果。

沙箱调试 ​

如需查看本接口可返回的字段结构，可请求沙箱地址：

https://sandbox.seermartech.cn/v3/serp/youtube/organic/task_get/advanced/00000000-0000-0000-0000-000000000000

沙箱返回的是带有模拟数据的完整字段结构，不会产生费用。

响应结构 ​

接口返回 JSON 对象 tasks 数组，每个任务项对应一个结果集合。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本。
status_codeinteger接口通用状态码。完整错误码请参考文档中的错误码附录。建议在系统中做好异常与错误处理。
status_messagestring通用状态信息。
timestring接口执行耗时，单位秒。
costfloat本次请求总费用，单位 USD。扣费请以该字段为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorinteger返回错误的任务数。
tasksarray任务结果数组。

tasks[] 字段 ​

字段名类型说明
idstring任务 ID，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态说明。
timestring任务执行耗时，单位秒。
costfloat单个任务费用，单位 USD。
result_countintegerresult 数组中的数量。
patharrayURL 路径信息。
dataobject与创建任务时提交的参数一致。
resultarray获取结果数组。

result[] 字段说明 ​

字段名类型说明
keywordstring创建任务时提交的。返回时会对 %## 进行解码，+ 号会被还原为空格。
se_domainstring创建任务时使用的搜索引擎域名。
location_codeinteger创建任务时使用的位置编码。
language_codestring创建任务时使用的语言编码。
check_urlstring指向搜索结果页的直达链接，可用于校验结果准确性。
datetimestring结果采集时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
spellobject搜索引擎自动纠错信息；如发生拼写修正，这里会返回修正后的及纠错类型。
refinement_chipsobject搜索细化标签。当前通常为 null。
item_typesarray当前 SERP 中出现的结果类型列表。
se_results_countintegerSERP 结果总数。
items_countintegeritems 数组中返回的结果数量。
itemsarraySERP 结果项。

item_types 可选值 ​

  • youtube_channel
  • youtube_video
  • youtube_video_paid

说明：从返回示例来看，结果中还可能出现 youtube_playlist 类型，建议按响应做容处理。

items[] 结果项类型 ​

1) youtube_channel ​

表示与搜索词的 YouTube 频道。

字段名类型说明
typestring固定为 youtube_channel。
rank_groupinteger分组排名；只在同类型结果中排序。
rank_absoluteintegerSERP 中的绝对排名。
block_rankinteger所属区块在 SERP 中的排名。
block_namestring所属区块名称，例如 "People also watched"。
channel_idstring频道 ID。
namestring频道名称。
urlstring频道链接。
logostring频道头像图片所在页面 URL。
video_countinteger频道视频数量。
is_verifiedboolean是否带有认证标识。
descriptionstring频道简介。
highlightedarray简介中高亮的。

2) youtube_video ​

表示自然视频结果。

字段名类型说明
typestring固定为 youtube_video。
rank_groupinteger分组排名。
rank_absoluteintegerSERP 中的绝对排名。
block_rankinteger所属区块排名。
block_namestring所属区块名称。
titlestring视频标题。
urlstring视频链接。
video_idstring视频 ID。
thumbnail_urlstring缩略图所在页面 URL。
channel_idstring发布频道 ID。
channel_namestring发布频道名称。
channel_urlstring发布频道链接。
channel_logostring频道头像图片所在页面 URL。
descriptionstring视频描述。
highlightedarray描述中高亮的。
badgesarray视频标签，例如 New、CC、4K。
is_liveboolean是否为直播。
is_shortsboolean是否为 Shorts。
is_movieboolean是否为电影。
views_countinteger播放量。
publication_datestring展示的发布时间。
timestampstring结果中的发布时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
duration_timestring视频时长，如 23:26。
duration_time_secondsinteger视频时长，单位秒。

3) youtube_video_paid ​

表示付费推广视频结果。

字段名类型说明
typestring固定为 youtube_video_paid。
rank_groupinteger分组排名。
rank_absoluteintegerSERP 中的绝对排名。
block_rankinteger所属区块排名。
block_namestring所属区块名称。
titlestring视频标题。
urlstring视频链接。
video_idstring视频 ID。
thumbnail_urlstring缩略图所在页面 URL。
channel_idstring发布频道 ID。
channel_namestring发布频道名称。
channel_urlstring发布频道链接。
channel_logostring频道头像图片所在页面 URL。
descriptionstring视频描述。
highlightedarray描述中高亮的。
badgesarray视频标签。
is_liveboolean是否为直播。
is_shortsboolean是否为 Shorts。
is_movieboolean是否为电影。
views_countinteger播放量。
publication_datestring展示的发布时间。
timestampstring结果中的发布时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
duration_timestring视频时长。
duration_time_secondsinteger视频时长，单位秒。

4) youtube_playlist ​

表示播放列表结果。

字段名类型说明
typestring固定为 youtube_playlist。
rank_groupinteger分组排名。
rank_absoluteintegerSERP 中的绝对排名。
block_rankinteger所属区块排名。
block_namestring所属区块名称。
titlestring播放列表标题。
urlstring播放列表链接。
playlist_idstring播放列表 ID。
thumbnail_urlstring缩略图所在页面 URL。
channel_idstring发布频道 ID。
channel_namestring发布频道名称。
channel_urlstring发布频道链接。
channel_logostring频道头像图片所在页面 URL。
videos_countinteger播放列表中的视频数量。
preview_videosarray预览视频列表。

preview_videos[] 字段 ​

字段名类型说明
video_idstring视频 ID。
titlestring视频标题。
urlstring视频链接。
duration_timestring视频时长。
duration_time_secondsinteger视频时长，单位秒。

请求示例 ​

cURL ​

bash
id="02261816-2027-0066-0000-c27d02864073"

curl --location --request GET "https://api.seermartech.cn/v3/serp/youtube/organic/task_get/advanced/${id}" \
 --header "Authorization: Bearer smt_live_YOUR_KEY" \
 --header "Content-Type: application/json"

Python ​

python
import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"

url = f"https://api.seermartech.cn/v3/serp/youtube/organic/task_get/advanced/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/youtube/organic/task_get/advanced/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

结果获取流程示例 ​

通常建议按以下流程使用：

  1. 通过任务提交接口创建 YouTube Organic 查询任务；
  2. 再调用 /v3/serp/youtube/organic/tasks_ready 获取已完成任务列表；
  3. 对每个已完成任务，调用 /v3/serp/youtube/organic/task_get/advanced/$id 拉取高级结果。

响应示例 ​

json
{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0791 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "youtube",
 "se_type": "organic",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "audi",
 "priority": 2,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 32447281,
 "items_count": 66,
 "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 是否为 20000。
  • 再逐个检查 tasks[].status_code，确认任务是否成功。
  • 当 tasks[].result 为空，或状态码大于等于 40000 时，应按失败任务处理。
  • 建议对以下做重试或告警：
  • 任务尚未完成
  • 任务 ID 不存在或已过期
  • 请求频率过高
  • 权限或认证失败

实用场景 ​

  • 监控品牌词视频：按品牌词抓取 YouTube 自然结果，识别品牌官方频道、视频与播放列表的排名，评估品牌覆盖度。
  • 分析竞品频道占位：查询竞品在 YouTube 搜索中的视频、频道和付费视频分布，判断竞品策略与投放强度。
  • 筛选可合作创：从结果中的频道信息、认证状态、视频与播放列表占位中，快速发现领域高频道。
  • 识别 Shorts 与直播机会：基于 is_shorts、is_live 等字段判断当前下哪些形态更容易获得展示，为选题提供依据。
  • 复核搜索结果真实性：利用 check_url 回看搜索结果页，质检采集结果、排查排名波动或异常数据。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API