YouTube Hashtag Search
YouTube 话题标签信息流是与主题标签相关联的公开视频集合，包含标题、描述、频道身份、缩略图、时长、发布信息和可见互动指标。这些记录可用于主题梳理、活动参与内容复核、Shorts 抽样和内容对比分析。
主要特性
- 话题标签信息流发现无需提供视频或频道 URL，即可发现与指定话题标签关联的公开视频。
- 全部内容与 Shorts 模式将 content_type 设为 all 可采集公开的信息流，设为 shorts 可仅采集 Shorts 样本。
- 视频与频道上下文返回标题、描述、频道身份、缩略图、时长、发布信息以及可见观看、点赞和评论数。
- 保留来源标签每条保存的视频记录都会包含为该结果保留的标准化来源话题标签。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
hashtags | 必填 | 一个或多个非空话题标签；开头的 # 可省略，并会在采集前移除。 |
results_limit | 可选 | 每个话题标签最多采集的视频数，范围为 20 到 2,000，默认值为 100。 |
content_type | 可选 | 内容模式：all 表示公开的话题标签信息流，shorts 表示仅返回 Shorts；默认值为 all。 |
如何使用
先选择能够表达研究主题边界的标签；需要比较样本时，为各组标签保持一致的内容模式和每标签结果上限。
- 准备一个或多个非空话题标签，可带或不带开头的 #，并选择 all 或 shorts。
- 向 /v1/youtube/hashtag-search POST hashtags、results_limit 和 content_type。
- 保存返回的 task_id，并轮询 /v1/tasks/{task_id}，直到任务成功或失败。
- 从 data.results.items 读取标准化视频；has_more 为 true 时继续使用 next_cursor。
curl -X POST "https://api.socq.ai/v1/youtube/hashtag-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hashtags":["#technology"],"results_limit":20,"content_type":"shorts"}'
# 轮询 GET /v1/tasks/{task_id}
# 从 data.results.items 读取记录，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 活动参与内容复核： 结合话题标签信息流样本、视频描述、频道身份和可见互动指标，复核公开的活动参与内容。
- Shorts 主题抽样： 选择 shorts 模式，构建与某个主题标签关联的短视频样本。
- 主题数据集准备： 把视频 ID、URL、发布信息、频道上下文、指标和保留的来源标签整理为结构化研究数据集。
使用建议
- 提交前统一标签格式，避免 #technology 和 technology 触发重复采集。
- 需要区分重叠信息流的准确来源时，每个任务只提交一个标签，因为重复视频只保存一次并保留一个来源标签。
- 把 results_limit 视为每标签上限；信息流结束或符合条件的视频较少时，采集会提前停止。
- 比较内容形式时应分别采集 all 与 shorts 样本，避免混合信息流影响短视频子集。
- 将缩略图和来源 URL 视为引用，不要假设它们是永久媒体下载地址。
相关 API
需要其他类型的 YouTube 公开数据时，可以使用以下 API。
- YouTube Channel Videos API — 通过频道 URL 采集公开普通视频，不包含 Shorts 和直播。
- YouTube Comments API — 采集公开评论、作者、互动、来源视频和对话关系。
- YouTube Transcripts API — 获取可用纯文本字幕，并支持可选语言。
- YouTube Channels API — 获取公开频道身份、图片、认证状态和可见受众统计。
- YouTube Videos API — 获取已知视频或 Short URL 的元数据、缩略图、时长和互动指标。
- YouTube Shorts API — 按频道采集公开 Shorts、缩略图、时长、发布时间和互动指标。
- YouTube Search API — 按关键词搜索公开普通视频，并支持元数据筛选。
- YouTube Channel Live Videos API — 从频道直播页采集公开播出记录，并返回来源信息与可见互动指标。
- YouTube Comment Replies API — 使用回复令牌继续读取已知 YouTube 评论下的公开回复，返回作者、互动和父评论信息。
- YouTube Community Posts API — 通过频道 URL 采集公开社区帖子，返回正文、频道身份、发布时间、图片引用和来源关系。
- YouTube Playlist Videos API — 通过公开播放列表 URL 或 ID 采集视频身份、频道信息、缩略图、时长和播放列表来源。