YouTube 自然搜索实时高级结果

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

本接口使用 POST /v3/serp/youtube/organic/live/advanced，实时获取指定在 YouTube 搜索结果中的高级数据。接口最多返回搜索结果页前 20 个结果区块，并根据指定的地区和语言返回对应结果。

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

请求地址

http

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

计费说明

每次请求按返回的 SERP 数据计费。参考价约 ¥0.0144 / 次，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

block_depth 设置为大于 20 的值时，如果搜索引擎返回 20 个结果区块，可能产生额外费用。如果指定深度高于返回结果数量，未使用部分会自动退还至账户余额。

认证方式

请求头使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求参数

主要参数

参数	类型	填	说明
`keyword`	string	是	要查询的 YouTube 搜索，最长 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`，最大值为 `200`。

> location_code 与 location_name 二选一；language_code 与 language_name 二选一。

附加参数

参数	类型	填	说明
`location_name`	string	条件填	搜索地区名。未指定 `location_code` 时填写。示例：`United States`。
`language_name`	string	条件填	搜索语言名。未指定 `language_code` 时填写。示例：`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",
      "device": "desktop",
      "os": "windows"
    }
  ]'

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",
}

# 每个请求只能提交一个任务
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "audi",
        "device": "desktop",
        "os": "windows",
    }
]

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

if response.ok:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
        # 在此处理返回结果
    else:
        print(
            "错误代码：%s，错误信息：%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 请求失败：%s" % response.status_code)

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/youtube/organic/live/advanced",
  [
    {
      language_code: "en",
      location_code: 2840,
      keyword: "audi",
      device: "desktop",
      os: "windows",
    },
  ],
  {
    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	当前 API 版本。
`status_code`	integer	顶层响应状态码。成功通常为 `20000`。
`status_message`	string	顶层响应说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中执行失败的任务数。
`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	请求 URL 路径信息。
`data`	object	请求中提交的任务参数。
`result`	array	SERP 结果数组。

`result` 结果字段

字段	类型	说明
`keyword`	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/null	搜索细化选项。本接口返回 `null`。
`item_types`	array	SERP 中出现的结果类型。可能：`youtube_channel`、`youtube_video`、`youtube_video_paid`、`youtube_playlist`。
`se_results_count`	integer	SERP 中的结果总数。
`items_count`	integer	`items` 数组中返回的结果数量。
`items`	array	SERP 结果项数组。

`items` 结果项

所有结果项通常以下排名字段：

字段	类型	说明
`type`	string	结果类型。
`rank_group`	integer	同一 `type` 类型结果中的组排名。不同类型结果之间不会连续计算该排名。
`rank_absolute`	integer	结果在整个 SERP 中的绝对排名。
`block_rank`	integer	结果区块在整个 SERP 中的排名。
`block_name`	string/null	SERP 区块名称，例如 `People also watched`。

`youtube_channel`：YouTube 频道

字段	类型	说明
`type`	string	固定为 `youtube_channel`。
`channel_id`	string	频道 ID。
`name`	string	频道名称。
`url`	string	频道 URL。
`logo`	string	频道 Logo 图片地址。
`video_count`	integer	频道中的视频数量。
`is_verified`	boolean	是否显示已验证标识。
`description`	string	频道描述。
`highlighted`	array	描述中被高亮显示的。

该类型还通用排名字段：rank_group、rank_absolute、block_rank、block_name。

`youtube_video`：YouTube 视频

字段	类型	说明
`type`	string	固定为 `youtube_video`。
`title`	string	视频标题。
`url`	string	视频 URL。
`video_id`	string	视频 ID。
`thumbnail_url`	string	视频缩略图地址。
`channel_id`	string	发布该视频的频道 ID。
`channel_name`	string	发布该视频的频道名称。
`channel_url`	string	频道 URL。
`channel_logo`	string	频道 Logo 图片地址。
`description`	string	视频描述。
`highlighted`	array	描述中被高亮显示的。
`badges`	array	视频徽章，例如 `New`、`CC`、`4K`。
`is_live`	boolean	是否为直播视频。
`is_shorts`	boolean	是否为 Shorts 短视频。
`is_movie`	boolean/null	是否为电影。
`views_count`	integer	视频观看次数。
`publication_date`	string	视频发布时间，例如 `43 minutes ago`。
`timestamp`	string	视频发布时间戳，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`duration_time`	string	视频时长，例如 `23:26`。
`duration_time_seconds`	integer	视频时长，单位为秒。

该类型还通用排名字段：rank_group、rank_absolute、block_rank、block_name。

`youtube_video_paid`：YouTube 付费视频结果

该类型字段与 youtube_video 基本一致，用于表示 SERP 中的付费视频结果。

字段	类型	说明
`type`	string	固定为 `youtube_video_paid`。
`title`	string	视频标题。
`url`	string	视频 URL。
`video_id`	string	视频 ID。
`thumbnail_url`	string	视频缩略图地址。
`channel_id`	string	发布频道 ID。
`channel_name`	string	发布频道名称。
`channel_url`	string	频道 URL。
`channel_logo`	string	频道 Logo 图片地址。
`description`	string	视频描述。
`highlighted`	array	描述中被高亮显示的。
`badges`	array	视频徽章，例如 `New`、`CC`、`4K`。
`is_live`	boolean	是否为直播视频。
`is_shorts`	boolean	是否为 Shorts 短视频。
`is_movie`	boolean/null	是否为电影。
`views_count`	integer	视频观看次数。
`publication_date`	string	视频发布时间。
`timestamp`	string	视频发布时间戳，UTC 格式。
`duration_time`	string	视频时长。
`duration_time_seconds`	integer	视频时长，单位为秒。

该类型还通用排名字段：rank_group、rank_absolute、block_rank、block_name。

`youtube_playlist`：YouTube 播放列表

字段	类型	说明
`type`	string	固定为 `youtube_playlist`。
`title`	string	播放列表标题。
`url`	string	播放列表 URL。
`playlist_id`	string	播放列表 ID。
`thumbnail_url`	string	播放列表缩略图地址。
`channel_id`	string	所属频道 ID。
`channel_name`	string	所属频道名称。
`channel_url`	string	所属频道 URL。
`channel_logo`	string/null	频道 Logo 图片地址。
`videos_count`	integer	播放列表中的视频数量。
`preview_videos`	array	播放列表预览视频信息。

该类型还通用排名字段：rank_group、rank_absolute、block_rank、block_name。

`preview_videos` 字段

字段	类型	说明
`video_id`	string	视频 ID。
`title`	string	视频标题。
`url`	string	视频 URL。
`duration_time`	string	视频时长。
`duration_time_seconds`	integer	视频时长，单位为秒。

响应示例

json

{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "11.0835 sec.",
  "cost": 0.0144,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "10.9521 sec.",
      "cost": 0.0144,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "youtube",
        "organic",
        "live",
        "advanced"
      ],
      "data": {
        "api": "serp",
        "function": "live",
        "se": "youtube",
        "se_type": "organic",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "audi",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "audi",
          "se_domain": "youtube.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.youtube.com/results?search_query=audi",
          "datetime": "2022-12-30 14:12:23 +00:00",
          "spell": null,
          "refinement_chips": null,
          "item_types": [
            "youtube_video",
            "youtube_channel",
            "youtube_playlist"
          ],
          "se_results_count": 32629053,
          "items_count": 3,
          "items": [
            {
              "type": "youtube_video",
              "rank_group": 1,
              "rank_absolute": 1,
              "block_rank": 1,
              "block_name": null,
              "title": "Audi video",
              "url": "https://www.youtube.com/watch?v=example",
              "video_id": "example",
              "thumbnail_url": "https://i.ytimg.com/vi/example/hqdefault.jpg",
              "channel_id": "UCexample",
              "channel_name": "Audi",
              "channel_url": "https://www.youtube.com/@Audi",
              "channel_logo": null,
              "description": "Video description",
              "highlighted": [],
              "badges": [
                "4K"
              ],
              "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/example",
              "video_count": 0,
              "is_verified": true,
              "description": "The official Audi YouTube Channel.",
              "highlighted": []
            },
            {
              "type": "youtube_playlist",
              "rank_group": 2,
              "rank_absolute": 3,
              "block_rank": 3,
              "block_name": null,
              "title": "Audi playlist",
              "url": "https://www.youtube.com/playlist?list=example",
              "playlist_id": "example",
              "thumbnail_url": "https://i.ytimg.com/vi/example/hqdefault.jpg",
              "channel_id": "UCexample",
              "channel_name": "Audi",
              "channel_url": "https://www.youtube.com/@Audi",
              "channel_logo": null,
              "videos_count": 81,
              "preview_videos": [
                {
                  "video_id": "example",
                  "title": "Audi video",
                  "url": "https://www.youtube.com/watch?v=example",
                  "duration_time": "23:26",
                  "duration_time_seconds": 1406
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

请根据顶层 status_code 和任务级 status_code 判断请求及任务是否成功。20000 表示成功，状态码表示请求或任务处理异常。

建议客户端同时检查：

HTTP 状态码；
顶层 status_code；
tasks_error；
每个任务的 status_code；
status_message 中的错误说明。

完整错误码请参考错误码文档。

实用场景

监控排名：实时查询 YouTube 的自然结果、频道、视频和播放列表排名，评估视频 SEO 优化效果。
分析竞品表现：获取竞品频道、视频的排名、观看次数、发布时间和时长，识别竞品在目标上的优势。
发现视频机会：按地区、语言和设备分析 SERP 结果类型，挖掘适合制作视频、Shorts 或播放列表的。
追踪付费与自然结果：区分 youtube_video 和 youtube_video_paid，评估广告与自然在搜索结果中的。
构建审计报表：结合 block_rank、rank_absolute、badges、is_live 等字段，批量生成 YouTube 搜索结果和特征分析报表。

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

请求地址 ​

计费说明 ​

认证方式 ​

请求参数 ​

主要参数 ​

附加参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 结果字段 ​

items 结果项 ​

youtube_channel：YouTube 频道 ​

youtube_video：YouTube 视频 ​

youtube_video_paid：YouTube 付费视频结果 ​

youtube_playlist：YouTube 播放列表 ​

preview_videos 字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​

YouTube 自然搜索实时高级结果

请求地址

计费说明

认证方式

请求参数

主要参数

附加参数

请求示例

cURL

Python

TypeScript

响应结构

顶层字段

任务字段

`result` 结果字段

`items` 结果项

`youtube_channel`：YouTube 频道

`youtube_video`：YouTube 视频

`youtube_video_paid`：YouTube 付费视频结果

`youtube_playlist`：YouTube 播放列表

`preview_videos` 字段

响应示例

状态码与错误处理

实用场景