Skip to content

Всё для WordPress, веб-разработки — и не только

🔍 Поиск видео на YouTube через Data API v3: полное руководство
Веб-разработкаПрограммы и сервисы
7 мин1,377 слов4 326

🔍 Поиск видео на YouTube через Data API v3: полное руководство

Сайту нужна лента видео с YouTube, а готового плагина под задачу нет, и вы уже представляете неделю возни с OAuth, токенами и кривыми библиотеками. YouTube Data API v3 закрывает эту задачу за час. Без OAuth, без токенов пользователя, без единой внешней зависимости. Только API-ключ и правильно собранный URL.

Поисковый эндпоинт отдаёт видео, каналы и плейлисты по ключевым словам. Фильтрует по дате, длительности, каналу. Сортирует по релевантности или просмотрам. На практике этого хватает для большинства сценариев, от ленты видео конкретного канала до подборки «wordpress tutorial» за последний месяц.

Ниже, пошаговый разбор с живыми примерами запросов и PHP-кодом. К концу вы соберёте рабочий поисковый модуль: структурированный JSON на входе, галерея видео на выходе, ноль сторонних библиотек.

💡 Быстрый обзор:

  • Создайте проект в консоли Google Cloud, включите YouTube Data API v3 и получите API-ключ.
  • Соберите URL поискового запроса: эндпоинт /youtube/v3/search, обязательные параметры part=snippet, key и q (с июня 2025 q обязателен, без него API возвращает пустой массив).
  • Добавьте фильтры: type (video/channel/playlist), channelId, publishedAfter/publishedBefore, maxResults, order, videoDuration, videoEmbeddable.
  • Выполните запрос через cURL в PHP, разберите JSON-ответ, выведите результаты и настройте кэширование через WordPress transient.

Шаг 1: Получаем API-ключ

Без ключа ни один запрос к API не уходит. Ключ привязывается к проекту в Google Cloud Console и идентифицирует ваше приложение, ничего сложнее логина в Google-аккаунт не потребуется.

Порядок действий:

  • Откройте Google Cloud Console и создайте новый проект или выберите существующий.
  • Перейдите в APIs & Services → Library, найдите «YouTube Data API v3» и нажмите Enable.
  • Откройте APIs & Services → Credentials, нажмите Create Credentials → API Key.
  • Скопируйте ключ. Сразу задайте ограничение: Restrict Key → YouTube Data API v3, чтобы ключ не использовали для других сервисов Google.

Ключ выглядит как строка вроде AIzaSyD-... и передаётся в каждом запросе параметром key. Для публичного поиска видео этого достаточно, OAuth не нужен. Но если вы планируете запросы от имени пользователя (загрузка видео, управление плейлистами), потребуется OAuth 2.0.

Быстрая проверка: отправьте GET-запрос к эндпоинту search с любым поисковым словом. Приходит JSON с массивом items, ключ работает.

Шаг 2: URL поискового запроса и обязательные параметры

Эндпоинт для поиска:

1GET https://www.googleapis.com/youtube/v3/search

Два параметра обязательны всегда:

Параметр

Назначение

part

Какие свойства ресурса включить в ответ. Для поиска нужен snippet. Именно snippet содержит поля title, description, thumbnails и channelTitle.

key

Ваш API-ключ.

q

Поисковый запрос. Принимает свободный текст, как в строке поиска на youtube.com.

Параметр q принимает свободный текст, как в строке поиска на youtube.com. Можно передавать несколько слов через пробел или плюс: q=wordpress+speed+optimization. Регистр не важен.

Минимальный работающий запрос:

1https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress&key=ВАШ_КЛЮЧ

Он вернёт 5 результатов (значение по умолчанию), столько отдаёт API, когда maxResults не переопределён.

Параметр type сужает тип искомого ресурса:

  • video, только видео;
  • channel, только каналы;
  • playlist, только плейлисты.

Можно перечислить через запятую: type=video,channel. Если не указан, API ищет всё подряд. Остальные параметры опциональны, но именно они превращают сырой запрос в точный инструмент.

Шаг 3: Поиск видео по ключевым словам

Классический сценарий: пользователь вводит поисковую фразу на сайте, вы отправляете её в YouTube API и показываете подборку видео.

Пример запроса для поиска видео по слову «swimming»:

1https://www.googleapis.com/youtube/v3/search?part=snippet&q=swimming&type=video&key=ВАШ_КЛЮЧ

Ответ приходит в JSON. Внутри items[], массив найденных ресурсов. Для каждого видео доступны:

  • id.videoId, уникальный идентификатор (подставляется в https://www.youtube.com/watch?v=...);
  • snippet.title, название видео;
  • snippet.description, описание;
  • snippet.thumbnails, превью в нескольких разрешениях (default, medium, high);
  • snippet.channelTitle, название канала.

На PHP проще всего забрать ответ через file_get_contents. Код с минимальной обработкой:

1$apiKey = 'ВАШ_КЛЮЧ';
2$query  = 'swimming';
3$url    = "https://www.googleapis.com/youtube/v3/search?part=snippet&q={$query}&type=video&key={$apiKey}";
4 
5$response = file_get_contents($url);
6$data     = json_decode($response, true);
7 
8foreach ($data['items'] as $item) {
9    echo '<h3>' . htmlspecialchars($item['snippet']['title']) . '</h3>';
10    echo '<p>' . htmlspecialchars($item['snippet']['description']) . '</p>';
11    echo '<img src="' . $item['snippet']['thumbnails']['medium']['url'] . '" alt="">';
12    echo '<a href="https://www.youtube.com/watch?v=' . $item['id']['videoId'] . '">Смотреть</a>';
13}

file_get_contents годится для тестов и небольших проектов. На production-сайтах лучше использовать cURL: он даёт контроль над таймаутами, заголовками и обработкой ошибок. И да, если allow_url_fopen выключен на хостинге, file_get_contents для внешних URL не сработает. В этом случае только cURL.

Шаг 4: Получаем видео с конкретного канала

Чтобы собрать все видео канала, передайте параметр channelId. Идентификатор канала найти легко: откройте страницу канала на YouTube, из адресной строки скопируйте значение после /channel/ (например UC3VyA8KN_VgCF93EurnAQXw).

Запрос:

1https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UC3VyA8KN_VgCF93EurnAQXw&type=video&order=date&key=ВАШ_КЛЮЧ

Параметр order=date сортирует по дате публикации, сначала новые. Без него API вернёт наиболее релевантные, но для ленты канала логичнее хронологический порядок.

Тот же запрос на PHP с cURL и базовой обработкой ошибок:

1$apiKey    = 'ВАШ_КЛЮЧ';
2$channelId = 'UC3VyA8KN_VgCF93EurnAQXw';
3$url       = "https://www.googleapis.com/youtube/v3/search?part=snippet&channelId={$channelId}&type=video&order=date&key={$apiKey}";
4 
5$ch = curl_init();
6curl_setopt_array($ch, [
7    CURLOPT_URL            => $url,
8    CURLOPT_RETURNTRANSFER => true,
9    CURLOPT_TIMEOUT        => 15,
10    CURLOPT_SSL_VERIFYPEER => true,
11]);
12 
13$response = curl_exec($ch);
14$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
15curl_close($ch);
16 
17if ($httpCode !== 200) {
18    echo 'Ошибка запроса. Код: ' . $httpCode;
19    exit;
20}
21 
22$data = json_decode($response, true);
23 
24foreach ($data['items'] as $item) {
25    printf(
26        '<div><a href="https://www.youtube.com/watch?v=%s">%s</a></div>',
27        $item['id']['videoId'],
28        htmlspecialchars($item['snippet']['title'])
29    );
30}

Канал может иметь сотни видео, а один запрос возвращает не больше 50. Чтобы забрать всё, используйте параметр pageToken из ответа API: передайте его значение в следующем запросе как pageToken=<токен>. Повторяйте, пока nextPageToken не станет пустым.

Шаг 5: Ограничение, сортировка и квоты

На реальном сайте редко нужны «все видео по запросу». Чаще, топ-10 за месяц или подборка, исключающая Shorts. Для этого API даёт пять параметров точной настройки.

maxResults, сколько элементов вернуть. Допустимые значения: от 1 до 50. По умолчанию 5. Для галереи или ленты ставьте 20-30, но помните о квотах.

order, поле сортировки:

Значение

Что делает

relevance

По релевантности запросу (по умолчанию)

date

Сначала новые

rating

По рейтингу (лайки/дизлайки)

viewCount

По числу просмотров

title

По алфавиту названий

publishedAfter** / **publishedBefore, фильтр по дате публикации. Формат: ISO 8601 (RFC 3339). Пример: publishedAfter=2026-01-01T00:00:00Z. Отсекает архивные видео, когда нужно только свежее.

videoDuration, фильтр по длительности:

  • short, до 4 минут;
  • medium, от 4 до 20 минут;
  • long, дольше 20 минут;
  • не указан, все.

videoEmbeddable со значением true отбирает только видео, разрешённые для встраивания на сторонние сайты. Для сайта, который встраивает плеер YouTube, это обязательный параметр.

Собранный вместе запрос: 10 embeddable-видео по WordPress, не старше 2026 года, длиннее 4 минут, отсортированных по просмотрам:

1https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress+tutorial&type=video&videoEmbeddable=true&videoDuration=medium&publishedAfter=2026-01-01T00:00:00Z&maxResults=10&order=viewCount&key=ВАШ_КЛЮЧ

Квоты: как не остаться с пустым экраном

Каждый поисковый запрос search.list расходует 100 единиц суточной квоты. По умолчанию проект Google Cloud получает 10 000 единиц в день бесплатно, это примерно 100 поисковых вызовов. Для сайта с посещаемостью выше ста человек в день этого мало.

Решение, кэшировать ответы API. В WordPress для этого идеально подходит механизм transients:

1$cache_key = 'yt_search_' . md5($query);
2$videos    = get_transient($cache_key);
3 
4if ($videos === false) {
5    $response = wp_remote_get($url);
6    $body     = json_decode(wp_remote_retrieve_body($response), true);
7    $videos   = $body['items'] ?? [];
8 
9    set_transient($cache_key, $videos, 6 * HOUR_IN_SECONDS);
10}
11 
12// Вывод $videos в галерею...

Шестичасовой transient означает максимум 4 запроса к API в сутки на одну поисковую фразу. Даже при десяти разных запросах на страницах сайта вы укладываетесь в 40 вызовов, меньше половины дневной квоты. Если нужно больше, квоту расширяют через заявку в Google Cloud Console: Quotas → YouTube Data API v3 → Edit.

Живой пример выше: сборка галереи видео с канала через Data API v3 на PHP за 15 минут.

⁉️🤔 Частые вопросы

Нужен ли OAuth для поиска видео через YouTube API?

Нет. Для поисковых запросов к /youtube/v3/search достаточно API-ключа. OAuth требуется только для операций от имени пользователя: загрузка видео, управление плейлистами, подписки. API-ключ получают в Google Cloud Console за пару минут и сразу используют.

Сколько запросов в день можно сделать бесплатно?

Каждый проект Google Cloud получает 10 000 единиц квоты в сутки бесплатно. Один вызов search.list расходует 100 единиц, это около 100 поисковых запросов в день. С кэшированием через WordPress transient этого хватает для среднего сайта. Нужно больше, квоту расширяют через заявку в Google Cloud Console (раздел Quotas).

Как получить больше 50 результатов по одному запросу?

Через пейджинг. В JSON-ответе API возвращает поле nextPageToken. Передайте его значение как параметр pageToken в следующем запросе, получите следующую страницу. Повторяйте, пока nextPageToken не станет пустым. Один полный проход по каналу с 500 видео, это 10 запросов и 1 000 единиц квоты.

Можно ли искать видео на других языках помимо английского?

Да. Параметр q принимает любой язык, включая русский. Алгоритм поиска YouTube сам определяет языковую релевантность. Для принудительного сужения добавьте параметр relevanceLanguage=ru, результаты будут отранжированы в пользу русскоязычного контента.

Почему API возвращает пустой массив, хотя запрос правильный?

Самая частая причина: publishedAfter установлен в будущее или на сегодняшнюю дату с точным временем. Используйте начало дня: T00:00:00Z. Вторая причина: комбинация фильтров, исключающая все результаты. Например, videoDuration=long и videoEmbeddable=true вместе с channelId маленького канала могут не дать ни одного совпадения. Упростите запрос до part=snippet&q=...&key=... и добавляйте фильтры по одному, проверяя результат на каждом шаге.

Собрать поиск за час: что ставить под конкретную задачу

Выбор инструмента зависит от того, что именно вы строите. Если нужна простая галерея видео канала на сайте-визитке, берите готовую PHP-обёртку вроде madcoda/php-youtube-api: Composer-пакет, три строки кода, результат за пять минут. Если строите кастомный поиск с фильтрами, кэшированием и пагинацией, пишите свой обработчик на cURL плюс WordPress transient. Для высоконагруженного сайта с десятками тысяч посетителей добавьте слой Redis-кэша поверх transients и настройте фоновую синхронизацию через WP-Cron, тогда страница отдаётся за миллисекунды, а квоты API расходуются только на инвалидацию кэша.

API-ключ у вас уже есть. Кэширование настроено. Осталось собрать URL под свою задачу и написать цикл вывода. Результат, живая лента видео, которая не зависит от сторонних сервисов и не упирается в квоты.

Редакция
РедакцияРедакционная команда→ Все публикации

Профессиональная команда авторов и редакторов, специализирующихся на создании качественного контента.