YouTube API 文档

YouTube API: 搜索 — 按国家获取直播视频

根据用户查询在 YouTube 上发现搜索数据,并将结果接入搜索、目录或研究界面。

当不知道确切的对象 ID、需要先找到相关候选项时,请使用“按国家获取直播视频”。

方法 GET
实体 搜索
版本 2
此端点的作用

利用此 API 方法可以构建什么

先查看结果和常见工作流,然后再了解参数和可运行的请求示例。

此端点可以帮助您

响应包含匹配的搜索、公开上下文,以及在有更多结果时的分页数据。

何时使用

当不知道确切的对象 ID、需要先找到相关候选项时,请使用“按国家获取直播视频”。

常见使用场景

产品内搜索

在面向客户的界面和内部界面中加入 YouTube 数据搜索。

构建目录

按查询查找候选项,并保存相关对象以供后续补全。

市场研究

收集结果集,用于主题、创作者和竞品分析。

可用版本

响应版本

两个版本完成相同的任务,接受相同的参数。使用切换按钮比较响应结构,并选择您的客户端所需的版本。

响应版本 V2

在本页面切换版本,即可在同一文档 URL 下比较响应结构。

保持不变的部分

V1 和 V2 的身份验证、必填参数和请求结构均相同。实际上,您只需在构建端点路径和解析响应时选择版本。

版本之间的差异

主要区别在于响应结构。新集成请使用 V2;仅在需要兼容现有客户端契约时保留 V1。

使用方法

如何调用该方法

两个版本使用相同的 API 密钥请求头和相同的查询参数。本文档先展示共享的参数集合,然后展示各版本特定的端点路径和代码片段。

输入参数

共享参数
参数 必填 类型 示例 说明
country_code 是 str US Two-letter ISO 3166-1 alpha-2 country code used for YouTube localization. Example: US.
query 是 str technology review 用户输入的搜索关键词。
cursor 否 str | None cursor-next-page 上一次响应返回的下一页游标。获取第一页时请省略。

各版本的请求路径

V2

复制确切的端点路径、示例 URL 和代码片段时请选择版本。上方的参数列表保持不变。

GET /api/v2/youtube.com/search/live-videos-by-country

规范化格式

代码示例

curl --request GET \
  --url "https://www.scrapestorm.net/api/v2/youtube.com/search/live-videos-by-country" \
  --header "X-API-Key: 00000000-0000-4000-8000-000000000000" \
  --get --data-urlencode 'country_code=US' \
  --get --data-urlencode 'query=technology review' \
  # Optional parameters:
  # --data-urlencode 'cursor=cursor-next-page'
响应示例

按版本查看真实响应

预览保留了关键字段和集合中的前几项,便于您快速浏览响应结构。切换版本会改变 JSON 格式。

响应示例

V2 响应 JSON

已验证示例

此简明 JSON 示例来自 V2 最近一次成功的验证运行。

{
  "success": true,
  "status": "ok",
  "pagination": {
    "cursor": "QVFB...",
    "has_more": true
  },
  "search_context": {
    "query": "technology review",
    "country_code": "US"
  },
  "data": {
    "videos": {
      "count": 20,
      "items": [
        {
          "author": {
            "url": "https://www.youtube.com/@BloombergPodcasts",
            "channel_id": "UChF5O40UBqAc82I7-i5ig6A",
            "username": "BloombergPodcasts",
            "display_name": "Bloomberg Podcasts"
          },
          "url": "https://www.youtube.com/watch?v=f39oHo6vFLg&pp=ygURdGVjaG5vbG9neSByZXZpZXc%3D",
          "video_id": "f39oHo6vFLg",
          "title": "Bloomberg Live: Business, Finance, Earnings & Investment News | Watch 7AM - 6PM ET Weekdays",
          "snippet": "Bloomberg Live: Business, Finance, Earnings & Investment News | Watch 7AM - 6PM ET Weekdays Subscribe to our Podcasts: ...",
          "view_count": 102,
          "badges": [
            "LIVE",
            "Verified"
          ],
          "thumbnail_url": "https://example.com/image.jpg",
          "thumbnails": [
            {
              "url": "https://i.ytimg.com/vi/f39oHo6vFLg/hq720.jpg?v=69c14078&sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAw-hwt307PV4xe4iatj9a6oQIOUQ",
              "width": 360,
              "height": 202
            },
            {
              "url": "https://i.ytimg.com/vi/f39oHo6vFLg/hq720.jpg?v=69c14078&sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBH9hq6ycb48hi-yaX6c5wSqD70aw",
              "width": 720,
              "height": 404
            }
          ],
          "is_live": true
        },
        {
          "author": {
            "url": "https://www.youtube.com/@YahooFinance",
            "channel_id": "UCEAZeUIeJs0IjQiqTCdVSIg",
            "username": "YahooFinance",
            "display_name": "Yahoo Finance"
          },
          "url": "https://www.youtube.com/watch?v=KQp-e_XQnDE&pp=ygURdGVjaG5vbG9neSByZXZpZXc%3D",
          "video_id": "KQp-e_XQnDE",
          "title": "Yahoo Finance 24/7 Stream: Daily Market Coverage & more",
          "snippet": "Live programming schedule (ET) 9:00am Morning Brief 9:30am Opening Bid 10:00am Market Catalysts 12:00pm The Daily Wolf ...",
          "view_count": 63,
          "badges": [
            "LIVE",
            "Verified"
          ],
          "thumbnail_url": "https://example.com/image.jpg",
          "thumbnails": [
            {
              "url": "https://i.ytimg.com/vi/KQp-e_XQnDE/hq720.jpg?v=69c6a8cc&sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBa0GQ1e5wV2xesTKTAdXmrXojvPA",
              "width": 360,
              "height": 202
            },
            {
              "url": "https://i.ytimg.com/vi/KQp-e_XQnDE/hq720.jpg?v=69c6a8cc&sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLCQr6d_KsRb6PCTNa99EA2WD_mBTw",
              "width": 720,
              "height": 404
            }
          ],
          "is_live": true
        },
        {
          "_more_items": 18
        }
      ]
    }
  }
}
下一步

继续评估

将本文档作为第一个决策点,然后在将端点接入常规使用之前,继续了解价格、平台覆盖范围和集成规则。

打开 YouTube 平台页面

在实现之前,比较相邻的实体、API 方法分组和相关文档。

打开平台页面

比较 API 方法价格

在扩大使用规模之前,查看此 API 方法在公开价格表中的位置。

查看价格

查看集成规则

通过入门文档确认身份验证、版本管理、重试以及模拟环境与正式环境的差异。

打开文档
常见问题

团队在实现前常问的问题

借助这些解答,判断此 API 方法是否适合您的工作流、版本选择和上线计划。

此 YouTube API 方法返回哪些数据?

该方法针对搜索执行“按国家获取直播视频”操作。下方的简明响应示例展示了确切的字段结构。

应该选择 V1 还是 V2?

新集成请选择 V2,因为它提供规范化的结构。仅在兼容已使用平台原生格式的客户端时使用 V1。

第一个请求需要准备什么?

创建 API 密钥,在请求头中发送它,并提供表格中的必填参数。代码示例中已包含正确的路径和请求结构。