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/all-by-country

规范化格式

代码示例

curl --request GET \
  --url "https://www.scrapestorm.net/api/v2/youtube.com/search/all-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": {
    "estimated_results": 13105432,
    "videos": {
      "count": 18,
      "items": [
        {
          "author": {
            "url": "https://www.youtube.com/@howtomen",
            "channel_id": "UCqjVP9gAanUGFgTA5BRDvyA",
            "username": "howtomen",
            "display_name": "HowToMen"
          },
          "url": "https://www.youtube.com/watch?v=m9mCqZ7tmUg&pp=ygURdGVjaG5vbG9neSByZXZpZXc%3D",
          "video_id": "m9mCqZ7tmUg",
          "title": "CES 2026: 20 Best Tech You’ll Actually Want!",
          "snippet": "Here are the Best Gadgets at CES 2026 that will make you jealous that you don't own them! ▣ Aiper Learn more about AIPER ...",
          "published_time": "6 months ago",
          "duration_seconds": 1794,
          "duration_text": "29:54",
          "view_count": 836484,
          "badges": [
            "4K",
            "Verified"
          ],
          "thumbnail_url": "https://example.com/image.jpg",
          "thumbnails": [
            {
              "url": "https://i.ytimg.com/vi/m9mCqZ7tmUg/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLCxnjiJbLI1JSXtYNK8qUxr1GVkVA",
              "width": 360,
              "height": 202
            },
            {
              "url": "https://i.ytimg.com/vi/m9mCqZ7tmUg/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBhirVSDkOJPc8X8Ybe0hXCvyj5nA",
              "width": 720,
              "height": 404
            }
          ]
        },
        {
          "author": {
            "url": "https://www.youtube.com/@mkbhd",
            "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
            "username": "mkbhd",
            "display_name": "Marques Brownlee"
          },
          "url": "https://www.youtube.com/watch?v=86Gy035z_KA&pp=ygURdGVjaG5vbG9neSByZXZpZXc%3D",
          "video_id": "86Gy035z_KA",
          "title": "Apple Vision Pro Review: Tomorrow's Ideas... Today's Tech!",
          "snippet": "Apple Vision Pro is a glimpse into the future... with today'stechnologyActually using Vision Pro: ...",
          "published_time": "2 years ago",
          "duration_seconds": 1488,
          "duration_text": "24:48",
          "view_count": 8422625,
          "badges": [
            "4K",
            "CC",
            {
              "_more_items": 1
            }
          ],
          "thumbnail_url": "https://example.com/image.jpg",
          "thumbnails": [
            {
              "url": "https://i.ytimg.com/vi/86Gy035z_KA/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLDhQioYOOJmE0jdbgz-dgMbz_Gezw",
              "width": 360,
              "height": 202
            },
            {
              "url": "https://i.ytimg.com/vi/86Gy035z_KA/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLA30oDwu6ljfOAPwnTY2k6Jx9BKnA",
              "width": 720,
              "height": 404
            }
          ]
        },
        {
          "_more_items": 16
        }
      ]
    },
    "shorts": {
      "count": 25,
      "items": [
        {
          "url": "https://www.youtube.com/shorts/7x0JrWMqjsc",
          "video_id": "7x0JrWMqjsc",
          "title": "This 2016 Tech was SO Good",
          "view_count": 174000,
          "thumbnail_url": "https://example.com/image.jpg",
          "thumbnails": [
            {
              "url": "https://i.ytimg.com/vi/7x0JrWMqjsc/oardefault.jpg?sqp=-oaymwEdCJUDENAFSFWQAgHyq4qpAwwIARUAAIhCcAHAAQY=&rs=AOn4CLA_yarKrG6CNziCwjx1SGgP-XflEg&usqp=CCk",
              "width": 405,
              "height": 720
            },
            {
              "url": "https://i.ytimg.com/vi/7x0JrWMqjsc/oardefault.jpg?sqp=-oaymwEgCJUDEOAESFWQAgHyq4qpAw8IARUAAIhCcAHAAQbIAQE=&rs=AOn4CLAT_BxR9wpvatawgp01H4h9FmZeIA&usqp=CCk",
              "width": 405,
              "height": 608
            }
          ]
        },
        {
          "url": "https://www.youtube.com/shorts/KG6Nu72Avqg",
          "video_id": "KG6Nu72Avqg",
          "title": "This Product Shouldn't Exist",
          "view_count": 27000000,
          "thumbnail_url": "https://example.com/image.jpg",
          "thumbnails": [
            {
              "url": "https://i.ytimg.com/vi/KG6Nu72Avqg/oar2.jpg?sqp=-oaymwEdCJUDENAFSFWQAgHyq4qpAwwIARUAAIhCcAHAAQY=&rs=AOn4CLCf5-tbd6B6q643_eA7BbZdeY50bA&usqp=CCk",
              "width": 405,
              "height": 720
            },
            {
              "url": "https://i.ytimg.com/vi/KG6Nu72Avqg/oar2.jpg?sqp=-oaymwEgCJUDEOAESFWQAgHyq4qpAw8IARUAAIhCcAHAAQbIAQE=&rs=AOn4CLD5W-6PrtVI1pEn88EhiwjPL-8hxQ&usqp=CCk",
              "width": 405,
              "height": 608
            }
          ]
        },
        {
          "_more_items": 23
        }
      ]
    },
    "channels": {
      "count": 1,
      "items": [
        {
          "url": "https://www.youtube.com/@mobiletechreview",
          "channel_id": "UCW6J17hZ_Vgr6cQgd_kHt5A",
          "username": "mobiletechreview",
          "display_name": "MobileTechReview",
          "verified": true,
          "snippet": "Lisa Gade from MobileTechReview brings you videoreviewsof the latest mobiletechnology: smartphones, Android tablets, ...",
          "subscriber_count": 969000,
          "badges": [
            "Verified"
          ],
          "avatar_url": "https://example.com/image.jpg",
          "avatar_urls": "https://example.com/image.jpg"
        }
      ]
    },
    "playlists": {
      "count": 0,
      "items": []
    }
  }
}
下一步

继续评估

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

打开 YouTube 平台页面

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

打开平台页面

比较 API 方法价格

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

查看价格

查看集成规则

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

打开文档
常见问题

团队在实现前常问的问题

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

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

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

应该选择 V1 还是 V2?

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

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

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