此端点可以帮助您
响应包含匹配的搜索、公开上下文，以及在有更多结果时的分页数据。
何时使用
当不知道确切的对象 ID、需要先找到相关候选项时，请使用“Playlists By Country”。
此端点的作用
利用此 API 方法可以构建什么
先查看结果和常见工作流，然后再了解参数和可运行的请求示例。
常见使用场景
产品内搜索
在面向客户的界面和内部界面中加入 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/playlists-by-country代码示例
curl --request GET \
--url "https://www.scrapestorm.net/api/v2/youtube.com/search/playlists-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'from urllib.parse import urljoin
import requests
BASE_URL = "https://www.scrapestorm.net"
ENDPOINT = "/api/v2/youtube.com/search/playlists-by-country"
HEADERS = {"Accept": "application/json", "X-API-Key": "00000000-0000-4000-8000-000000000000"}
params = {
"country_code": "US",
"query": "technology review",
}
# Optional parameters
# params["cursor"] = "cursor-next-page"
with requests.Session() as session:
response = session.request(
method="GET",
url=urljoin(BASE_URL, ENDPOINT),
headers=HEADERS,
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
print(payload)const BASE_URL = "https://www.scrapestorm.net";
const endpoint = "/api/v2/youtube.com/search/playlists-by-country";
const params = new URLSearchParams({
country_code: "US",
query: "technology review",
});
// Optional parameters
// params.set("cursor", "cursor-next-page");
const response = await fetch(`${BASE_URL}${endpoint}?${params.toString()}`, {
method: "GET",
headers: {
Accept: "application/json",
"X-API-Key": "00000000-0000-4000-8000-000000000000",
},
});
if (!response.ok) {
throw new Error(`Request failed: ${response.status} ${response.statusText}`);
}
const payload = await response.json();
console.log(payload);import axios from "axios";
const client = axios.create({
baseURL: "https://www.scrapestorm.net",
timeout: 30000,
headers: {
Accept: "application/json",
"X-API-Key": "00000000-0000-4000-8000-000000000000",
},
});
const params = {
country_code: "US",
query: "technology review",
};
// Optional parameters
// params.cursor = "cursor-next-page";
const { data: payload } = await client.request({
method: "GET",
url: endpoint,
params,
});
console.log(payload);<?php
declare(strict_types=1);
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;
$client = new Client([
'base_uri' => "https://www.scrapestorm.net",
'timeout' => 30.0,
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => "00000000-0000-4000-8000-000000000000",
],
]);
$query = [
"country_code" => "US",
"query" => "technology review",
];
// Optional parameters
// $query["cursor"] = "cursor-next-page";
try {
$response = $client->request("GET", "/api/v2/youtube.com/search/playlists-by-country", [
'query' => $query,
]);
$payload = json_decode(
(string) $response->getBody(),
true,
512,
JSON_THROW_ON_ERROR
);
var_dump($payload);
} catch (GuzzleException $e) {
throw $e;
}package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"time"
)
func main() {
baseURL := "https://www.scrapestorm.net"
endpoint := "/api/v2/youtube.com/search/playlists-by-country"
params := url.Values{}
params.Set("country_code", "US")
params.Set("query", "technology review")
// Optional parameters
// params.Set("cursor", "cursor-next-page")
req, err := http.NewRequest(
"GET",
fmt.Sprintf("%s%s?%s", baseURL, endpoint, params.Encode()),
nil,
)
if err != nil {
panic(err)
}
req.Header.Set("Accept", "application/json")
req.Header.Set("X-API-Key", "00000000-0000-4000-8000-000000000000")
client := &http.Client{Timeout: 30 * time.Second}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var payload any
if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
panic(err)
}
fmt.Printf("%+v\n", payload)
}各版本的请求路径
V1复制确切的端点路径、示例 URL 和代码片段时请选择版本。上方的参数列表保持不变。
GET /api/v1/youtube.com/search/playlists-by-country代码示例
curl --request GET \
--url "https://www.scrapestorm.net/api/v1/youtube.com/search/playlists-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'from urllib.parse import urljoin
import requests
BASE_URL = "https://www.scrapestorm.net"
ENDPOINT = "/api/v1/youtube.com/search/playlists-by-country"
HEADERS = {"Accept": "application/json", "X-API-Key": "00000000-0000-4000-8000-000000000000"}
params = {
"country_code": "US",
"query": "technology review",
}
# Optional parameters
# params["cursor"] = "cursor-next-page"
with requests.Session() as session:
response = session.request(
method="GET",
url=urljoin(BASE_URL, ENDPOINT),
headers=HEADERS,
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
print(payload)const BASE_URL = "https://www.scrapestorm.net";
const endpoint = "/api/v1/youtube.com/search/playlists-by-country";
const params = new URLSearchParams({
country_code: "US",
query: "technology review",
});
// Optional parameters
// params.set("cursor", "cursor-next-page");
const response = await fetch(`${BASE_URL}${endpoint}?${params.toString()}`, {
method: "GET",
headers: {
Accept: "application/json",
"X-API-Key": "00000000-0000-4000-8000-000000000000",
},
});
if (!response.ok) {
throw new Error(`Request failed: ${response.status} ${response.statusText}`);
}
const payload = await response.json();
console.log(payload);import axios from "axios";
const client = axios.create({
baseURL: "https://www.scrapestorm.net",
timeout: 30000,
headers: {
Accept: "application/json",
"X-API-Key": "00000000-0000-4000-8000-000000000000",
},
});
const params = {
country_code: "US",
query: "technology review",
};
// Optional parameters
// params.cursor = "cursor-next-page";
const { data: payload } = await client.request({
method: "GET",
url: endpoint,
params,
});
console.log(payload);<?php
declare(strict_types=1);
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;
$client = new Client([
'base_uri' => "https://www.scrapestorm.net",
'timeout' => 30.0,
'headers' => [
'Accept' => 'application/json',
'X-API-Key' => "00000000-0000-4000-8000-000000000000",
],
]);
$query = [
"country_code" => "US",
"query" => "technology review",
];
// Optional parameters
// $query["cursor"] = "cursor-next-page";
try {
$response = $client->request("GET", "/api/v1/youtube.com/search/playlists-by-country", [
'query' => $query,
]);
$payload = json_decode(
(string) $response->getBody(),
true,
512,
JSON_THROW_ON_ERROR
);
var_dump($payload);
} catch (GuzzleException $e) {
throw $e;
}package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"time"
)
func main() {
baseURL := "https://www.scrapestorm.net"
endpoint := "/api/v1/youtube.com/search/playlists-by-country"
params := url.Values{}
params.Set("country_code", "US")
params.Set("query", "technology review")
// Optional parameters
// params.Set("cursor", "cursor-next-page")
req, err := http.NewRequest(
"GET",
fmt.Sprintf("%s%s?%s", baseURL, endpoint, params.Encode()),
nil,
)
if err != nil {
panic(err)
}
req.Header.Set("Accept", "application/json")
req.Header.Set("X-API-Key", "00000000-0000-4000-8000-000000000000")
client := &http.Client{Timeout: 30 * time.Second}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var payload any
if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
panic(err)
}
fmt.Printf("%+v\n", payload)
}
响应示例
按版本查看真实响应
预览保留了关键字段和集合中的前几项，便于您快速浏览响应结构。切换版本会改变 JSON 格式。
此简明 JSON 示例来自 V2 最近一次成功的验证运行。
{
"success": true,
"status": "ok",
"pagination": {
"cursor": "QVFB...",
"has_more": true
},
"search_context": {
"query": "technology review",
"country_code": "US"
},
"data": {
"playlists": {
"count": 20,
"items": [
{
"author": {
"url": "https://www.youtube.com/@technologyreview",
"channel_id": "UCgy4Mf_tlZGqesYNqPNxjPw",
"username": "technologyreview",
"display_name": "MIT Technology Review"
},
"url": "https://www.youtube.com/playlist?list=PL0VMbiSIIJY_McrDyks8X0NxR5Z31x4XN",
"playlist_id": "PL0VMbiSIIJY_McrDyks8X0NxR5Z31x4XN",
"title": "Events by MIT Technology Review",
"playlist_type": "playlist",
"video_count": 15,
"content_count_text": "15 videos",
"first_video_id": "qjISMaWFCd0",
"first_video_url": "https://www.youtube.com/watch?v=qjISMaWFCd0&list=PL0VMbiSIIJY_McrDyks8X0NxR5Z31x4XN",
"thumbnail_url": "https://example.com/image.jpg",
"thumbnails": [
{
"url": "https://i.ytimg.com/vi/qjISMaWFCd0/hqdefault.jpg?sqp=-oaymwEXCOADEI4CSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLD9gvD31eWHXTl7sLlAUqI9L_hPcQ",
"width": 480,
"height": 270
}
]
},
{
"author": {
"url": "https://www.youtube.com/@mkbhd",
"channel_id": "UCBJycsmduvYEL83R_U4JriQ",
"username": "mkbhd",
"display_name": "Marques Brownlee"
},
"url": "https://www.youtube.com/playlist?list=PLBsP89CPrMeNm71T5gYC6jebm9vPbLBiP",
"playlist_id": "PLBsP89CPrMeNm71T5gYC6jebm9vPbLBiP",
"title": "Reviews!",
"playlist_type": "series",
"video_count": 323,
"content_count_text": "323 episodes",
"first_video_id": "DUgPFNRmsCQ",
"first_video_url": "https://www.youtube.com/watch?v=DUgPFNRmsCQ&list=PLBsP89CPrMeNm71T5gYC6jebm9vPbLBiP",
"thumbnail_url": "https://example.com/image.jpg",
"thumbnails": [
{
"url": "https://i.ytimg.com/vi/DUgPFNRmsCQ/hq720.jpg?sqp=-oaymwEXCOgCEMoBSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLDN3DGjsDXR16-47pR3ST91sV64-w",
"width": 360,
"height": 202
},
{
"url": "https://i.ytimg.com/vi/DUgPFNRmsCQ/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLAsLbR4fy5ZnQ_liUygU1n6ZtW0BA",
"width": 720,
"height": 404
}
]
},
{
"_more_items": 18
}
]
}
}
}此简明 JSON 示例来自 V1 最近一次成功的验证运行。
{
"success": true,
"status": "ok",
"pagination": {
"cursor": "QVFB...",
"has_more": true
},
"search_context": {
"query": "technology review",
"country_code": "US"
},
"data": {
"responseContext": {
"serviceTrackingParams": [
{
"service": "GUIDED_HELP",
"params": [
{
"key": "context",
"value": "yt_web_search"
},
{
"key": "logged_in",
"value": "0"
}
]
},
{
"service": "GFEEDBACK",
"params": [
{
"key": "has_unlimited_entitlement",
"value": "False"
},
{
"key": "has_premium_lite_entitlement",
"value": "False"
},
{
"_more_items": 2
}
]
},
{
"_more_items": 2
}
],
"mainAppWebResponseContext": {
"loggedOut": true,
"trackingParam": "k5_fmPxhoXZR7HSIVAuq6U-PVVXOEIrucdEaldzOgANPb5TeaU1o1MBXqzRMkuMESLBwOcCw59TLtslLKPQGSS"
},
"responseId": "IhMIgNncl9XflQMVtt_OAB3dBSSW",
"webResponseContextExtensionData": {
"webResponseContextPreloadData": {
"preloadMessageNames": [
"twoColumnSearchResultsRenderer",
"sectionListRenderer",
{
"_more_items": 32
}
]
},
"hasDecorated": true
}
},
"estimatedResults": "310629",
"contents": {
"twoColumnSearchResultsRenderer": {
"primaryContents": {
"sectionListRenderer": {
"contents": [
"…",
"…"
],
"trackingParams": "CDwQui8iEwiA2dyX1d-VAxW2384AHd0FJJY=",
"subMenu": {
"searchSubMenuRenderer": "…"
},
"hideBottomSeparator": true,
"targetId": "search-feed"
}
}
}
},
"trackingParams": "CAAQvGkiEwiA2dyX1d-VAxW2384AHd0FJJbKAQRetfVv",
"header": {
"searchHeaderRenderer": {
"chipBar": {
"chipCloudRenderer": {
"chips": [
"…",
"…",
{
"_more_items": 5
}
],
"trackingParams": "CDIQkVoiEwiA2dyX1d-VAxW2384AHd0FJJY=",
"nextButton": {
"buttonRenderer": "…"
},
"previousButton": {
"buttonRenderer": "…"
}
}
},
"searchFilterButton": {
"buttonRenderer": {
"style": "STYLE_TEXT",
"size": "SIZE_DEFAULT",
"isDisabled": false,
"text": {
"runs": "…"
},
"icon": {
"iconType": "TUNE"
},
"tooltip": "Search filters",
"trackingParams": "CBMQ8FsiEwiA2dyX1d-VAxW2384AHd0FJJY=",
"accessibilityData": {
"accessibilityData": "…"
},
"command": {
"clickTrackingParams": "CBMQ8FsiEwiA2dyX1d-VAxW2384AHd0FJJbKAQRetfVv",
"openPopupAction": "…"
},
"iconPosition": "BUTTON_ICON_POSITION_TYPE_RIGHT_OF_TEXT"
}
},
"trackingParams": "CBIQiOoKIhMIgNncl9XflQMVtt_OAB3dBSSW"
}
},
"topbar": {
"desktopTopbarRenderer": {
"logo": {
"topbarLogoRenderer": {
"iconImage": {
"iconType": "YOUTUBE_LOGO"
},
"tooltipText": {
"runs": "…"
},
"endpoint": {
"clickTrackingParams": "CBEQsV4iEwiA2dyX1d-VAxW2384AHd0FJJbKAQRetfVv",
"commandMetadata": "…",
"browseEndpoint": "…"
},
"trackingParams": "CBEQsV4iEwiA2dyX1d-VAxW2384AHd0FJJY=",
"overrideEntityKey": "EgZ0b3BiYXIg9QEoAQ%3D%3D"
}
},
"searchbox": {
"fusionSearchboxRenderer": {
"icon": {
"iconType": "SEARCH"
},
"placeholderText": {
"runs": "…"
},
"config": {
"webSearchboxConfig": "…"
},
"trackingParams": "CA0Q7VAiEwiA2dyX1d-VAxW2384AHd0FJJY=",
"searchEndpoint": {
"clickTrackingParams": "CA0Q7VAiEwiA2dyX1d-VAxW2384AHd0FJJbKAQRetfVv",
"commandMetadata": "…",
"searchEndpoint": "…"
},
"clearButton": {
"buttonRenderer": "…"
},
"showImageSourceDialog": {
"clickTrackingParams": "CA0Q7VAiEwiA2dyX1d-VAxW2384AHd0FJJbKAQRetfVv",
"showDialogCommand": "…"
},
"disableAiAppearance": true
}
},
"trackingParams": "CAEQq6wBIhMIgNncl9XflQMVtt_OAB3dBSSW",
"topbarButtons": [
{
"topbarMenuButtonRenderer": {
"icon": "…",
"menuRequest": "…",
"trackingParams": "CAsQ_qsBGAAiEwiA2dyX1d-VAxW2384AHd0FJJY=",
"accessibility": "…",
"tooltip": "Settings",
"style": "STYLE_DEFAULT"
}
},
{
"buttonRenderer": {
"style": "STYLE_SUGGESTIVE",
"size": "SIZE_SMALL",
"text": "…",
"icon": "…",
"navigationEndpoint": "…",
"trackingParams": "CAoQ1IAEGAEiEwiA2dyX1d-VAxW2384AHd0FJJY=",
"targetId": "topbar-signin"
}
}
],
"hotkeyDialog": {
"hotkeyDialogRenderer": {
"title": {
"runs": "…"
},
"sections": [
"…",
"…",
{
"_more_items": 2
}
],
"dismissButton": {
"buttonRenderer": "…"
},
"trackingParams": "CAgQteYDIhMIgNncl9XflQMVtt_OAB3dBSSW"
}
},
"backButton": {
"buttonRenderer": {
"trackingParams": "CAcQvIYDIhMIgNncl9XflQMVtt_OAB3dBSSW",
"command": {
"clickTrackingParams": "CAcQvIYDIhMIgNncl9XflQMVtt_OAB3dBSSWygEEXrX1bw==",
"commandMetadata": "…",
"signalServiceEndpoint": "…"
}
}
},
"forwardButton": {
"buttonRenderer": {
"trackingParams": "CAYQvYYDIhMIgNncl9XflQMVtt_OAB3dBSSW",
"command": {
"clickTrackingParams": "CAYQvYYDIhMIgNncl9XflQMVtt_OAB3dBSSWygEEXrX1bw==",
"commandMetadata": "…",
"signalServiceEndpoint": "…"
}
}
},
"a11ySkipNavigationButton": {
"buttonRenderer": {
"style": "STYLE_DEFAULT",
"size": "SIZE_DEFAULT",
"isDisabled": false,
"text": {
"runs": "…"
},
"trackingParams": "CAUQ8FsiEwiA2dyX1d-VAxW2384AHd0FJJY=",
"command": {
"clickTrackingParams": "CAUQ8FsiEwiA2dyX1d-VAxW2384AHd0FJJbKAQRetfVv",
"commandMetadata": "…",
"signalServiceEndpoint": "…"
}
}
},
"voiceSearchButton": {
"buttonRenderer": {
"style": "STYLE_DEFAULT",
"size": "SIZE_DEFAULT",
"isDisabled": false,
"serviceEndpoint": {
"clickTrackingParams": "CAIQ7a8FIhMIgNncl9XflQMVtt_OAB3dBSSWygEEXrX1bw==",
"commandMetadata": "…",
"signalServiceEndpoint": "…"
},
"icon": {
"iconType": "MICROPHONE_ON"
},
"tooltip": "Search with your voice",
"trackingParams": "CAIQ7a8FIhMIgNncl9XflQMVtt_OAB3dBSSW",
"accessibilityData": {
"accessibilityData": "…"
}
}
}
}
},
"targetId": "search-page"
}
}
下一步
继续评估
将本文档作为第一个决策点，然后在将端点接入常规使用之前，继续了解价格、平台覆盖范围和集成规则。
常见问题
团队在实现前常问的问题
借助这些解答，判断此 API 方法是否适合您的工作流、版本选择和上线计划。
此 YouTube API 方法返回哪些数据？
该方法针对搜索执行“Playlists By Country”操作。下方的简明响应示例展示了确切的字段结构。
应该选择 V1 还是 V2？
新集成请选择 V2，因为它提供规范化的结构。仅在兼容已使用平台原生格式的客户端时使用 V1。
第一个请求需要准备什么？
创建 API 密钥，在请求头中发送它，并提供表格中的必填参数。代码示例中已包含正确的路径和请求结构。