YouTube 的视频关键词搜索核心是YouTube Data API v3 的 search.list 接口（对应item_search_video功能），输入关键词即可按类型 / 时长 / 发布时间 / 互动量等多维度筛选全球公开视频，返回分页视频列表（含基础元数据与创作者信息），并可联动videos.list（item_get_video）获取单视频精细化详情Google for Developers。该接口采用 API 密钥 / OAuth2.0 双认证，配额严格且按调用单位计费，本攻略从接口认知、权限获取、全流程代码、调试排错到生产级优化，提供结构化全链路指导，兼顾入门易用性与企业级稳定性，助力高效完成跨境内容搜索与数据聚合对接。
一、接口核心认知：功能与适配场景
1. 接口定位与核心价值
2. 核心参数与返回字段
（1）请求参数（官方规范，必填 + 可选）
（2）返回核心字段（按业务场景分类）
3. 接口限制与注意事项
二、对接前准备：权限与环境搭建
1. 获取接口权限（官方唯一合规路径）
2. 技术环境准备
（1）支持语言与协议
（2）必备工具与依赖
三、实操步骤：接口对接全流程（Python 示例）
步骤 1：理解认证与配额规则
（1）API 密钥认证（公开数据）
（2）OAuth2.0 授权（用户级数据）
步骤 2：完整代码实现（官方 SDK+HTTP 直连双示例）
（1）依赖安装
（2）官方 SDK 实现（推荐，配额更稳定）
import os
import time
import pandas as pd
import logging
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 日志配置
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
handlers=[logging.FileHandler("youtube_item_search_video.log"), logging.StreamHandler()]
)
# 配置（替换为你的API密钥）
API_KEY = "你的YouTube API密钥"
YOUTUBE_API_SERVICE_NAME = "youtube"
YOUTUBE_API_VERSION = "v3"
def build_youtube_client():
"""构建YouTube API客户端"""
return build(
YOUTUBE_API_SERVICE_NAME,
YOUTUBE_API_VERSION,
developerKey=API_KEY,
cache_discovery=False
)
def standardize_search_data(raw_item: dict) -> dict:
"""标准化搜索结果数据，统一输出格式"""
snippet = raw_item.get("snippet", {})
video_id = raw_item.get("id", {}).get("videoId", "")
published_at = snippet.get("publishedAt", "").replace("T", " ").replace("Z", "")
thumbnail_url = snippet.get("thumbnails", {}).get("high", {}).get("url", "")
return {
"搜索关键词": raw_item.get("keyword", ""),
"视频ID": video_id,
"标题": snippet.get("title", ""),
"描述": snippet.get("description", "")[:100] + "..." if len(snippet.get("description", "")) > 100 else snippet.get("description", ""),
"封面链接": thumbnail_url,
"发布时间": published_at,
"创作者ID": snippet.get("channelId", ""),
"创作者名称": snippet.get("channelTitle", ""),
"请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
}
def youtube_item_search_video(
keyword: str,
region: str = "US",
published_after: str = None,
published_before: str = None,
order: str = "relevance",
video_duration: str = "any",
max_results: int = 20,
page_token: str = None
) -> dict:
"""调用YouTube search.list接口获取关键词视频列表（官方SDK方式）"""
youtube = build_youtube_client()
try:
# 构建基础参数
params = {
"part": "snippet",
"q": keyword,
"type": "video",
"regionCode": region,
"order": order,
"videoDuration": video_duration,
"maxResults": min(max_results, 50), # 单次最多50条
"key": API_KEY
}
# 补充分页与时间参数
if page_token:
params["pageToken"] = page_token
if published_after and published_before:
params["publishedAfter"] = published_after
params["publishedBefore"] = published_before
request = youtube.search().list(**params)
response = request.execute()
items = response.get("items", [])
next_page_token = response.get("nextPageToken", "")
total_results = response.get("pageInfo", {}).get("totalResults", 0)
if not items:
logging.warning("无视频数据返回")
return {
"success": False,
"error_msg": "无视频数据",
"data": [],
"next_page_token": "",
"total_results": 0
}
# 标准化数据并添加关键词标识
for item in items:
item["keyword"] = keyword
standard_videos = [standardize_search_data(item) for item in items]
return {
"success": True,
"data": standard_videos,
"next_page_token": next_page_token,
"total_results": total_results,
"error_msg": ""
}
except HttpError as e:
error_msg = f"HTTP错误：{e.resp.status} - {e.content.decode('utf-8')}"
logging.error(error_msg)
return {
"success": False,
"error_msg": error_msg,
"data": [],
"next_page_token": "",
"total_results": 0
}
except Exception as e:
logging.error(f"调用异常：{str(e)}")
return {
"success": False,
"error_msg": str(e),
"data": [],
"next_page_token": "",
"total_results": 0
}
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 调用示例：搜索“smartphone review”，美国地区，近30天，按观看量排序
if __name__ == "__main__":
keyword = "smartphone review"
region = "US"
published_after = "2025-11-29T00:00:00Z" # 近30天
published_before = "2025-12-29T00:00:00Z"
order = "viewCount"
max_results = 20
first_page_result = youtube_item_search_video(
keyword=keyword,
region=region,
published_after=published_after,
published_before=published_before,
order=order,
max_results=max_results
)
if first_page_result["success"]:
print(f"获取到 {len(first_page_result['data'])} 条视频数据，总计约 {first_page_result['total_results']} 条")
for video in first_page_result["data"][:5]:
print(f"标题：{video['标题']} | 视频ID：{video['视频ID']} | 创作者：{video['创作者名称']}")
# 翻页示例：获取下一页
if first_page_result["next_page_token"]:
second_page_result = youtube_item_search_video(
keyword=keyword,
region=region,
published_after=published_after,
published_before=published_before,
order=order,
max_results=max_results,
page_token=first_page_result["next_page_token"]
)
print(f"下一页获取到 {len(second_page_result['data'])} 条视频数据")
else:
print(f"获取失败：{first_page_result['error_msg']}")（3）HTTP 直连实现（无 SDK 场景）
import requests
def youtube_http_item_search(keyword: str, api_key: str, max_results: int = 20) -> dict:
"""HTTP直连调用YouTube搜索接口"""
url = "https://www.googleapis.com/youtube/v3/search"
params = {
"part": "snippet",
"q": keyword,
"type": "video",
"maxResults": max_results,
"key": api_key
}
response = requests.get(url, params=params)
return response.json()
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 调用示例
api_key = "你的API密钥"
keyword = "smartphone review"
result = youtube_http_item_search(keyword, api_key, max_results=10)
print(result)