🔍 Ricerca di video su YouTube con Data API v3: una guida completa
Il tuo sito ha bisogno di un feed video YouTube, ma non esiste un plugin già pronto per questo compito e stai già immaginando una settimana di lotta con OAuth, token e librerie farraginose. L'API YouTube Data v3 gestisce questa attività in circa un'ora. Niente OAuth, niente token utente, nessuna dipendenza esterna. Solo una chiave API e un URL costruito correttamente.
L'endpoint di ricerca restituisce video, canali e playlist in base a parole chiave. Filtra per data, durata e canale. Ordina per pertinenza o numero di visualizzazioni. Nella pratica, questo copre la maggior parte degli scenari, dal feed video di un canale specifico a una raccolta di «tutorial wordpress» dell'ultimo mese.
Di seguito trovi una guida passo passo con esempi di richieste live e codice PHP. Alla fine avrai un modulo di ricerca funzionante: JSON strutturato in ingresso, galleria video in uscita, zero librerie di terze parti.
💡 Panoramica rapida:
- Crea un progetto nella console Google Cloud, abilita YouTube Data API v3 e ottieni una chiave API.
- Costruisci l'URL della richiesta di ricerca: endpoint
/youtube/v3/search, parametri obbligatoripart=snippet,keyeq(da giugno 2025qè obbligatorio; senza di esso l'API restituisce un array vuoto). - Aggiungi filtri: type (video/channel/playlist), channelId, publishedAfter/publishedBefore, maxResults, order, videoDuration, videoEmbeddable.
- Esegui la richiesta tramite cURL in PHP, analizza la risposta JSON, mostra i risultati e imposta la cache tramite i transients di WordPress.
Step 1: Ottenere la chiave API
Senza chiave, nessuna richiesta API parte. La chiave è legata a un progetto nella console Google Cloud e identifica la tua applicazione; non serve nulla di più complicato che accedere con un account Google.
Ecco cosa devi fare:
- Apri la console Google Cloud e crea un nuovo progetto o selezionane uno esistente.
- Vai su API e servizi → Libreria, cerca «YouTube Data API v3» e clicca su Abilita.
- Apri API e servizi → Credenziali, clicca su Crea credenziali → Chiave API.
- Copia la chiave. Imposta subito una restrizione: Limita chiave → YouTube Data API v3, così la chiave non può essere usata per altri servizi Google.
La chiave appare come una stringa tipo AIzaSyD-... e viene passata in ogni richiesta tramite il parametro key. Per la ricerca di video pubblici questo è sufficiente; OAuth non serve. Tuttavia, se prevedi richieste per conto di un utente (caricamento video, gestione playlist), ti servirà OAuth 2.0.
Test rapido: invia una richiesta GET all'endpoint search con un qualsiasi termine di ricerca. Se ricevi un JSON con un array items, la chiave funziona.
Step 2: URL della richiesta di ricerca e parametri obbligatori
Endpoint per la ricerca:
1 GET https://www.googleapis.com/youtube/v3/search
Due parametri sono sempre obbligatori:
Parametro | Scopo |
|---|---|
| Quali proprietà della risorsa includere nella risposta. Per la ricerca serve |
| La tua chiave API. |
| La query di ricerca. Accetta testo libero, proprio come la barra di ricerca su youtube.com. |
Il parametro q accetta testo libero, proprio come la barra di ricerca su youtube.com. Puoi passare più parole separate da spazi o segni più: q=wordpress+speed+optimization. Le maiuscole/minuscole non contano.
Richiesta minima funzionante:
1 https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress&key=YOUR_KEY
Restituirà 5 risultati (il valore predefinito), che è ciò che l'API restituisce quando maxResults non viene sovrascritto.
Il parametro type restringe il tipo di risorsa cercata:
video, solo video;channel, solo canali;playlist, solo playlist.
Puoi elencare più valori separati da virgole: type=video,channel. Se omesso, l'API cerca tutto. I parametri rimanenti sono opzionali, ma trasformano una query grezza in uno strumento preciso.
Step 3: Cercare video per parole chiave
Uno scenario classico: un utente inserisce una frase di ricerca sul tuo sito, tu la invii all'API di YouTube e mostri una selezione di video.
Esempio di richiesta per cercare video con la parola «swimming»:
1 https://www.googleapis.com/youtube/v3/search?part=snippet&q=swimming&type=video&key=YOUR_KEY
La risposta arriva in JSON. All'interno di items[] c'è un array di risorse trovate. Per ogni video hai:
id.videoId, l'identificatore univoco (da inserire inhttps://www.youtube.com/watch?v=...);snippet.title, il titolo del video;snippet.description, la descrizione;snippet.thumbnails, anteprime in diverse risoluzioni (default, medium, high);snippet.channelTitle, il nome del canale.
In PHP il modo più semplice per recuperare la risposta è tramite file_get_contents. Ecco un codice di elaborazione minimo:
1 $apiKey = 'YOUR_KEY'; 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 8 foreach ($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'] . '">Watch</a>'; 13 }
file_get_contents va bene per test e piccoli progetti. In produzione, usa cURL: ti dà il controllo su timeout, header e gestione degli errori. E sì, se allow_url_fopen è disabilitato sul tuo hosting, file_get_contents non funzionerà per URL esterni. In quel caso, cURL è la tua unica opzione.
Step 4: Recuperare i video da un canale specifico
Per raccogliere tutti i video di un canale, passa il parametro channelId. Trovare l'identificatore del canale è facile: apri la pagina del canale su YouTube e copia il valore dopo /channel/ dalla barra degli indirizzi (ad esempio UC3VyA8KN_VgCF93EurnAQXw).
Richiesta:
1 https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UC3VyA8KN_VgCF93EurnAQXw&type=video&order=date&key=YOUR_KEY
Il parametro order=date ordina per data di pubblicazione, dal più recente. Senza, l'API restituisce i risultati più pertinenti, ma per il feed di un canale l'ordine cronologico ha più senso.
La stessa richiesta in PHP con cURL e gestione base degli errori:
1 $apiKey = 'YOUR_KEY'; 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(); 6 curl_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); 15 curl_close($ch); 16 17 if ($httpCode !== 200) { 18 echo 'Request error. Code: ' . $httpCode; 19 exit; 20 } 21 22 $data = json_decode($response, true); 23 24 foreach ($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 }
Un canale può avere centinaia di video, ma una singola richiesta ne restituisce al massimo 50. Per recuperarli tutti, usa il campo pageToken dalla risposta API: passa il suo valore nella richiesta successiva come pageToken=<token>. Ripeti finché nextPageToken non è vuoto.
Step 5: Limiti, ordinamento e quote
Su un sito reale raramente servono «tutti i video per una query». Più spesso vuoi i primi 10 dell'ultimo mese o una selezione che escluda gli Shorts. Per questo, l'API fornisce cinque parametri di regolazione fine.
maxResults: quanti elementi restituire. Valori validi: da 1 a 50. Il valore predefinito è 5. Per una galleria o un feed, imposta 20-30, ma tieni a mente le quote.
order: campo di ordinamento:
Valore | Cosa fa |
|---|---|
| Per pertinenza alla query (predefinito) |
| Dal più recente |
| Per valutazione (mi piace/non mi piace) |
| Per numero di visualizzazioni |
| In ordine alfabetico per titolo |
publishedAfter** / **publishedBefore: filtra per data di pubblicazione. Formato: ISO 8601 (RFC 3339). Esempio: publishedAfter=2026-01-01T00:00:00Z. Taglia fuori i video archiviati quando ti serve solo contenuto fresco.
videoDuration: filtra per durata:
short, meno di 4 minuti;medium, da 4 a 20 minuti;long, oltre 20 minuti;- non specificato, tutti.
videoEmbeddable con valore true seleziona solo i video per cui è consentita l'incorporazione su siti di terze parti. Per un sito che incorpora il player YouTube, questo è un parametro obbligatorio.
Richiesta combinata: 10 video incorporabili su WordPress, non più vecchi del 2026, più lunghi di 4 minuti, ordinati per numero di visualizzazioni:
1 https://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=YOUR_KEY
Quote: come evitare una schermata vuota
Ogni chiamata search.list costa 100 unità della tua quota giornaliera. Per impostazione predefinita, un progetto Google Cloud riceve 10.000 unità al giorno gratuitamente, circa 100 chiamate di ricerca. Per un sito con più di cento visitatori al giorno, non è sufficiente.
La soluzione è memorizzare nella cache le risposte API. In WordPress, i transients funzionano perfettamente per questo:
1 $cache_key = 'yt_search_' . md5($query); 2 $videos = get_transient($cache_key); 3 4 if ($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 // Display $videos in a gallery...
Un transient di sei ore significa un massimo di 4 richieste API al giorno per una singola frase di ricerca. Anche con dieci query diverse tra le pagine del sito, resti sotto le 40 chiamate, meno della metà della quota giornaliera. Se ti serve di più, richiedi un aumento della quota tramite la console Google Cloud: Quote → YouTube Data API v3 → Modifica.
L'esempio live qui sopra mostra come costruire una galleria video di un canale tramite Data API v3 in PHP in 15 minuti.
⁉️🤔 Domande frequenti
Serve OAuth per cercare video tramite l'API di YouTube?
No. Per le richieste di ricerca a
/youtube/v3/searchbasta una chiave API. OAuth è richiesto solo per operazioni a livello utente: caricamento video, gestione playlist, iscrizioni. Una chiave API si ottiene nella console Google Cloud in un paio di minuti e si usa immediatamente.
Quante richieste al giorno si possono fare gratuitamente?
Ogni progetto Google Cloud riceve 10.000 unità di quota al giorno gratuitamente. Una chiamata
search.listcosta 100 unità, quindi circa 100 richieste di ricerca al giorno. Con la cache tramite i transients di WordPress, questo basta per un sito medio. Se ti serve di più, richiedi un aumento della quota tramite la console Google Cloud (sezione Quote).
Come ottengo più di 50 risultati da una singola query?
Tramite paginazione. Nella risposta JSON, l'API restituisce un campo
nextPageToken. Passa il suo valore come parametropageTokennella richiesta successiva per ottenere la pagina seguente. Ripeti finchénextPageTokennon è vuoto. Un passaggio completo su un canale con 500 video richiede 10 richieste e 1.000 unità di quota.
Posso cercare video in lingue diverse dall'inglese?
Sì. Il parametro
qaccetta qualsiasi lingua, incluso l'italiano. L'algoritmo di ricerca di YouTube determina automaticamente la pertinenza linguistica. Per forzare un restringimento, aggiungi il parametrorelevanceLanguage=ru; i risultati saranno classificati a favore dei contenuti in lingua russa.
Perché l'API restituisce un array vuoto anche se la richiesta è corretta?
La causa più comune:
publishedAfterè impostato su una data futura o sulla data odierna con un orario esatto. Usa l'inizio del giorno:T00:00:00Z. La seconda causa: una combinazione di filtri che esclude tutti i risultati. Ad esempio,videoDuration=longevideoEmbeddable=trueinsieme alchannelIddi un canale piccolo potrebbero dare zero corrispondenze. Semplifica la richiesta fino apart=snippet&q=...&key=...e aggiungi i filtri uno alla volta, controllando i risultati a ogni passaggio.
Costruire la ricerca in un'ora: quali strumenti per quale compito
La scelta degli strumenti dipende da cosa stai costruendo esattamente. Se ti serve una semplice galleria video per un canale su un piccolo sito aziendale, prendi un wrapper PHP già pronto come madcoda/php-youtube-api: un pacchetto Composer, tre righe di codice, risultato in cinque minuti. Se stai costruendo una ricerca personalizzata con filtri, cache e paginazione, scrivi il tuo gestore usando cURL più i transients di WordPress. Per un sito ad alto traffico con decine di migliaia di visitatori, aggiungi un layer di cache Redis sopra i transients e imposta la sincronizzazione in background tramite WP-Cron; così le pagine si caricano in millisecondi e le quote API vengono consumate solo per l'invalidazione della cache.
Hai già la tua chiave API. La cache è configurata. Non resta che assemblare l'URL per il tuo compito e scrivere il ciclo di output. Il risultato è un feed video live che non dipende da servizi di terze parti e non raggiunge i limiti di quota.
Un team professionale di scrittori e redattori specializzati nella creazione di contenuti di qualità.