Skip to content

Wszystko o WordPressie, tworzeniu stron — i nie tylko

🔍 Wyszukiwanie filmów na YouTube przez Data API v3: pełny przewodnik
Tworzenie stron WWWProgramy i usługi
7 min1,476 słów

🔍 Wyszukiwanie filmów na YouTube przez Data API v3: pełny przewodnik

Strona potrzebuje kanału wideo z YouTube, a gotowej wtyczki do tego zadania nie ma i już Pan/Pani wyobraża sobie tydzień problemów z OAuth, tokenami i kiepskimi bibliotekami. YouTube Data API v3 zamyka to zadanie w godzinę. Bez OAuth, bez tokenów użytkownika, bez żadnej zewnętrznej zależności. Tylko klucz API i poprawnie złożony URL.

Endpoint wyszukiwania zwraca filmy, kanały i playlisty według słów kluczowych. Filtruje według daty, czasu trwania, kanału. Sortuje według trafności lub liczby wyświetleń. W praktyce to wystarcza w większości scenariuszy, od kanału wideo konkretnego kanału po zestawienie „wordpress tutorial" z ostatniego miesiąca.

Poniżej analiza krok po kroku z działającymi przykładami zapytań i kodem PHP. Na końcu zbuduje Pan/Pani działający moduł wyszukiwania: ustrukturyzowany JSON na wejściu, galeria wideo na wyjściu, zero zewnętrznych bibliotek.

💡 Szybki przegląd:

  • Proszę utworzyć projekt w konsoli Google Cloud, włączyć YouTube Data API v3 i uzyskać klucz API.
  • Proszę złożyć URL zapytania wyszukiwania: endpoint /youtube/v3/search, obowiązkowe parametry part=snippet, key i q (od czerwca 2025 q jest obowiązkowy, bez niego API zwraca pustą tablicę).
  • Proszę dodać filtry: type (video/channel/playlist), channelId, publishedAfter/publishedBefore, maxResults, order, videoDuration, videoEmbeddable.
  • Proszę wykonać zapytanie przez cURL w PHP, sparsować odpowiedź JSON, wyświetlić wyniki i skonfigurować cache’owanie przez WordPress transient.

Krok 1: Uzyskanie klucza API

Bez klucza żadne zapytanie do API nie przejdzie. Klucz jest powiązany z projektem w Google Cloud Console i identyfikuje Pana/Pani aplikację, nie potrzeba niczego więcej niż logowanie na konto Google.

Kolejność działań:

  • Proszę otworzyć Google Cloud Console i utworzyć nowy projekt lub wybrać istniejący.
  • Proszę przejść do APIs & Services → Library, znaleźć „YouTube Data API v3" i kliknąć Enable.
  • Proszę otworzyć APIs & Services → Credentials, kliknąć Create Credentials → API Key.
  • Proszę skopiować klucz. Od razu proszę ustawić ograniczenia: Restrict Key → YouTube Data API v3, aby klucz nie był używany do innych usług Google.

Klucz ma postać ciągu znaków, np. AIzaSyD-... i jest przekazywany w każdym zapytaniu jako parametr key. Do publicznego wyszukiwania filmów to wystarcza, OAuth nie jest potrzebny. Jeśli jednak planuje Pan/Pani zapytania w imieniu użytkownika (przesyłanie filmów, zarządzanie playlistami), potrzebny będzie OAuth 2.0.

Szybkie sprawdzenie: proszę wysłać zapytanie GET do endpointu search z dowolnym słowem wyszukiwania. Jeśli przyjdzie JSON z tablicą items, klucz działa.

Krok 2: URL zapytania wyszukiwania i parametry obowiązkowe

Endpoint do wyszukiwania:

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

Dwa parametry są zawsze obowiązkowe:

Parametr

Przeznaczenie

part

Które właściwości zasobu uwzględnić w odpowiedzi. Do wyszukiwania potrzebny jest snippet. To właśnie snippet zawiera pola title, description, thumbnails i channelTitle.

key

Pana/Pani klucz API.

q

Zapytanie wyszukiwania. Przyjmuje dowolny tekst, jak w pasku wyszukiwania na youtube.com.

Parametr q przyjmuje dowolny tekst, jak w pasku wyszukiwania na youtube.com. Można przekazać kilka słów oddzielonych spacją lub plusem: q=wordpress+speed+optimization. Wielkość liter nie ma znaczenia.

Minimalne działające zapytanie:

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

Zwróci ono 5 wyników (wartość domyślna), tyle zwraca API, gdy maxResults nie jest nadpisane.

Parametr type zawęża typ szukanego zasobu:

  • video, tylko filmy;
  • channel, tylko kanały;
  • playlist, tylko playlisty.

Można wymienić po przecinku: type=video,channel. Jeśli nie podano, API szuka wszystkiego. Pozostałe parametry są opcjonalne, ale to właśnie one przekształcają surowe zapytanie w precyzyjne narzędzie.

Krok 3: Wyszukiwanie filmów według słów kluczowych

Klasyczny scenariusz: użytkownik wpisuje frazę wyszukiwania na stronie, Pan/Pani wysyła ją do YouTube API i pokazuje zestaw filmów.

Przykład zapytania do wyszukiwania filmów dla słowa „swimming":

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

Odpowiedź przychodzi w JSON. Wewnątrz items[], tablica znalezionych zasobów. Dla każdego filmu dostępne są:

  • id.videoId, unikalny identyfikator (podstawiany do https://www.youtube.com/watch?v=...);
  • snippet.title, tytuł filmu;
  • snippet.description, opis;
  • snippet.thumbnails, miniatury w kilku rozdzielczościach (default, medium, high);
  • snippet.channelTitle, nazwa kanału.

W PHP najprościej pobrać odpowiedź przez file_get_contents. Kod z minimalną obróbką:

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 nadaje się do testów i małych projektów. Na stronach produkcyjnych lepiej używać cURL: daje kontrolę nad timeoutami, nagłówkami i obsługą błędów. I tak, jeśli allow_url_fopen jest wyłączone na hostingu, file_get_contents dla zewnętrznych URL nie zadziała. W takim przypadku tylko cURL.

Krok 4: Pobieranie filmów z konkretnego kanału

Aby zebrać wszystkie filmy kanału, proszę przekazać parametr channelId. Identyfikator kanału łatwo znaleźć: proszę otworzyć stronę kanału na YouTube, z paska adresu skopiować wartość po /channel/ (na przykład UC3VyA8KN_VgCF93EurnAQXw).

Zapytanie:

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

Parametr order=date sortuje według daty publikacji, najpierw nowe. Bez niego API zwróci najtrafniejsze, ale dla kanału wideo bardziej logiczna jest kolejność chronologiczna.

To samo zapytanie w PHP z cURL i podstawową obsługą błędów:

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}

Kanał może mieć setki filmów, a jedno zapytanie zwraca nie więcej niż 50. Aby pobrać wszystko, proszę użyć parametru pageToken z odpowiedzi API: proszę przekazać jego wartość w następnym zapytaniu jako pageToken=<токен>. Proszę powtarzać, dopóki nextPageToken nie będzie pusty.

Krok 5: Ograniczenia, sortowanie i limity

Na realnej stronie rzadko potrzebne są „wszystkie filmy dla zapytania". Częściej top 10 za miesiąc lub zestawienie wykluczające Shorts. Do tego API daje pięć parametrów precyzyjnego dostrojenia.

maxResults, ile elementów zwrócić. Dopuszczalne wartości: od 1 do 50. Domyślnie 5. Dla galerii lub kanału proszę ustawić 20-30, ale proszę pamiętać o limitach.

order, pole sortowania:

Wartość

Co robi

relevance

Według trafności zapytania (domyślnie)

date

Najpierw nowe

rating

Według oceny (łapki w górę/w dół)

viewCount

Według liczby wyświetleń

title

Alfabetycznie według tytułów

publishedAfter** / **publishedBefore, filtr według daty publikacji. Format: ISO 8601 (RFC 3339). Przykład: publishedAfter=2026-01-01T00:00:00Z. Odcina archiwalne filmy, gdy potrzebne są tylko świeże.

videoDuration, filtr według czasu trwania:

  • short, do 4 minut;
  • medium, od 4 do 20 minut;
  • long, dłuższe niż 20 minut;
  • nie podano, wszystkie.

videoEmbeddable z wartością true wybiera tylko filmy, które można osadzać na stronach trzecich. Dla strony, która osadza odtwarzacz YouTube, jest to parametr obowiązkowy.

Złożone razem zapytanie: 10 filmów embeddable o WordPress, nie starszych niż 2026 rok, dłuższych niż 4 minuty, posortowanych według wyświetleń:

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=ВАШ_КЛЮЧ

Limity: jak nie zostać z pustym ekranem

Każde zapytanie wyszukiwania search.list zużywa 100 jednostek dziennego limitu. Domyślnie projekt Google Cloud otrzymuje 10 000 jednostek dziennie bezpłatnie, to około 100 wywołań wyszukiwania. Dla strony z odwiedzalnością powyżej stu osób dziennie to za mało.

Rozwiązanie: cache’ować odpowiedzi API. W WordPress idealnie nadaje się do tego mechanizm 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 в галерею...

Sześciogodzinny transient oznacza maksymalnie 4 zapytania do API na dobę na jedną frazę wyszukiwania. Nawet przy dziesięciu różnych zapytaniach na stronach serwisu zmieści się Pan/Pani w 40 wywołaniach, mniej niż połowa dziennego limitu. Jeśli potrzeba więcej, limit rozszerza się przez wniosek w Google Cloud Console: Quotas → YouTube Data API v3 → Edit.

Żywy przykład powyżej: zbudowanie galerii wideo z kanału przez Data API v3 w PHP w 15 minut.

⁉️🤔 Często zadawane pytania

Czy OAuth jest potrzebny do wyszukiwania filmów przez YouTube API?

Nie. Do zapytań wyszukiwania do /youtube/v3/search wystarczy klucz API. OAuth jest potrzebny tylko do operacji w imieniu użytkownika: przesyłania filmów, zarządzania playlistami, subskrypcji. Klucz API uzyskuje się w Google Cloud Console w kilka minut i od razu używa.

Ile zapytań dziennie można wykonać bezpłatnie?

Każdy projekt Google Cloud otrzymuje 10 000 jednostek limitu na dobę bezpłatnie. Jedno wywołanie search.list zużywa 100 jednostek, to około 100 zapytań wyszukiwania dziennie. Z cache’owaniem przez WordPress transient to wystarcza dla średniej wielkości strony. Jeśli potrzeba więcej, limit rozszerza się przez wniosek w Google Cloud Console (sekcja Quotas).

Jak uzyskać więcej niż 50 wyników w jednym zapytaniu?

Przez paginację. W odpowiedzi JSON API zwraca pole nextPageToken. Proszę przekazać jego wartość jako parametr pageToken w następnym zapytaniu, otrzyma Pan/Pani następną stronę. Proszę powtarzać, dopóki nextPageToken nie będzie pusty. Jedno pełne przejście kanału z 500 filmami to 10 zapytań i 1 000 jednostek limitu.

Czy można wyszukiwać filmy w innych językach niż angielski?

Tak. Parametr q przyjmuje dowolny język, w tym polski. Algorytm wyszukiwania YouTube sam określa trafność językową. Aby wymusić zawężenie, proszę dodać parametr relevanceLanguage=ru, wyniki zostaną uszeregowane na korzyść treści rosyjskojęzycznej.

Dlaczego API zwraca pustą tablicę, chociaż zapytanie jest poprawne?

Najczęstsza przyczyna: publishedAfter ustawione na przyszłość lub na dzisiejszą datę z dokładnym czasem. Proszę używać początku dnia: T00:00:00Z. Druga przyczyna: kombinacja filtrów, która wyklucza wszystkie wyniki. Na przykład videoDuration=long i videoEmbeddable=true razem z channelId małego kanału mogą nie dać żadnego trafienia. Proszę uprościć zapytanie do part=snippet&q=...&key=... i dodawać filtry pojedynczo, sprawdzając wynik na każdym kroku.

Zbudować wyszukiwanie w godzinę: co zastosować do konkretnego zadania

Wybór narzędzia zależy od tego, co dokładnie Pan/Pani buduje. Jeśli potrzebna jest prosta galeria wideo kanału na stronie wizytówce, proszę wziąć gotowe opakowanie PHP, takie jak madcoda/php-youtube-api: pakiet Composer, trzy linijki kodu, wynik w pięć minut. Jeśli buduje Pan/Pani niestandardowe wyszukiwanie z filtrami, cache’owaniem i paginacją, proszę napisać własny handler na cURL plus WordPress transient. Dla wysoko obciążonej strony z dziesiątkami tysięcy odwiedzających proszę dodać warstwę cache Redis na wierzchu transients i skonfigurować synchronizację w tle przez WP-Cron, wtedy strona jest dostarczana w milisekundach, a limity API są zużywane tylko na unieważnienie cache.

Klucz API już Pan/Pani ma. Cache’owanie jest skonfigurowane. Pozostaje złożyć URL pod swoje zadanie i napisać pętlę wyświetlania. Rezultat: żywy kanał wideo, który nie zależy od usług stron trzecich i nie blokuje się na limitach.

Redakcja
RedakcjaZespół redakcyjny→ All publications

Profesjonalny zespół autorów i redaktorów specjalizujących się w tworzeniu treści wysokiej jakości.