Skip to content

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

🔍 Пошук відео на YouTube через Data API v3: повне керівництво
Веб-розробкаПрограми та сервіси
7 хв1,383 слів2

🔍 Пошук відео на 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 під свою задачу та написати цикл виведення. Результат, жива стрічка відео, яка не залежить від сторонніх сервісів і не впирається в квоти.

Редакція
РедакціяРедакційна команда→ Усі публікації

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