Perché analizzare i dati video via API quando puoi semplicemente aprire la pagina?

Raccogliere manualmente informazioni su decine di video richiede ore. Titolo, durata, conteggio visualizzazioni, data di pubblicazione: copiare tutto questo a mano da YouTube è una strada garantita verso errori e burnout.

L'API YouTube Data v3 risolve il problema in modo programmatico. Una richiesta HTTP e ottieni JSON strutturato con snippet, contentDetails e statistics. Niente parsing HTML, niente captcha.

In questo tutorial: istruzioni passo passo dalla creazione di una chiave API fino a uno script PHP pronto all'uso che estrae informazioni su qualsiasi video YouTube dal suo URL. Il codice è reale, testato, con spiegazioni per ogni riga.

💡 Panoramica rapida:

• Creare una chiave API in Google Cloud Console e abilitare YouTube Data API v3
• Analizzare la struttura dell'endpoint /videos e i suoi parametri part, id e key
• Scrivere una funzione PHP per estrarre l'ID video da qualsiasi link YouTube
• Effettuare una richiesta tramite file_get_contents() e analizzare la risposta JSON
• Gestire gli errori: chiave non valida, ID errato, quota superata
• Esaminare un'alternativa: la libreria già pronta madcoda/php-youtube-api

Passo 1: Ottenere una chiave API YouTube Data

Per lavorare con l'API serve una chiave. Ecco il percorso più breve:

• Apri Google Cloud Console e crea un nuovo progetto (o selezionane uno esistente).
• Vai su API e servizi → Libreria, cerca "YouTube Data API v3" e clicca Abilita.
• Vai su Credenziali → Crea credenziali → Chiave API.
• (Consigliato) Limita la chiave: nella sezione Restrizioni API, seleziona YouTube Data API v3 così la chiave non funzionerà con altri servizi Google.

La chiave appare come una stringa tipo AIzaSyD-... di 39 caratteri. Senza di essa, l'API restituisce un errore 403.

La quota giornaliera è di 10.000 unità. Una richiesta a /videos costa 1 unità. Per test e piccoli progetti è più che sufficiente. Se prevedi un carico di produzione, richiedi un aumento della quota nella stessa sezione della Console.

Passo 2: Endpoint API e suoi parametri

URL per ottenere informazioni sul video:

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

I parametri vengono passati come query string:

Tre valori principali di part che coprono la maggior parte degli scenari:

• snippet: informazioni di base: titolo, descrizione, channelId, channelTitle, publishedAt, thumbnails (set di URL delle miniature a diverse risoluzioni), tags, categoryId.
• contentDetails: caratteristiche: durata (in formato ISO 8601, ad es. PT4M13S), dimensione (2d/3d), definizione (sd/hd), caption (se esistono sottotitoli).
• statistics: numeri: viewCount, likeCount, commentCount.

Nota importante: il campo dislikeCount in statistics è stato disabilitato da dicembre 2021, l'API restituisce sempre 0. Anche il campo favoriteCount è deprecato (sempre 0 da agosto 2015). Non fare affidamento su di essi nel tuo codice.

Passo 3: Estrarre l'ID video dall'URL

Prima di chiamare l'API, devi estrarre l'ID video dal link. YouTube ha diversi formati di URL:

• Standard: https://www.youtube.com/watch?v=1ejTKov_Sm4
• Breve: https://youtu.be/1ejTKov_Sm4
• Embed: https://www.youtube.com/embed/1ejTKov_Sm4
• Con parametri: https://www.youtube.com/watch?v=1ejTKov_Sm4&t=120

Una semplice funzione PHP gestisce tutte queste varianti:

1
/**
2
 * Extracts video ID from YouTube URL.
3
 * Supports formats: watch?v=, youtu.be/, /embed/
4
 *
5
 * @param string $url YouTube video URL
6
 * @return string|null Video ID (11 characters) or null on error
7
 */
8
function getYouTubeVideoId(string $url): ?string
9
{
10
    $parsed = parse_url($url);
11
 
12
    // Short link youtu.be/VIDEO_ID
13
    if (isset($parsed['host']) && str_contains($parsed['host'], 'youtu.be')) {
14
        return ltrim($parsed['path'], '/') ?: null;
15
    }
16
 
17
    // Standard link watch?v=VIDEO_ID
18
    if (isset($parsed['query'])) {
19
        parse_str($parsed['query'], $params);
20
        if (!empty($params['v'])) {
21
            return $params['v'];
22
        }
23
    }
24
 
25
    // Embed link /embed/VIDEO_ID
26
    if (isset($parsed['path']) && str_starts_with($parsed['path'], '/embed/')) {
27
        return substr($parsed['path'], 7);
28
    }
29
 
30
    return null;
31
}
32
 
33
// Usage example
34
$videoUrl = 'https://www.youtube.com/watch?v=1ejTKov_Sm4';
35
$videoId  = getYouTubeVideoId($videoUrl);
36
echo $videoId; // 1ejTKov_Sm4

La funzione utilizza solo funzionalità native di PHP: parse_url() scompone l'URL in componenti, parse_str() analizza la query string in un array. Nessuna dipendenza esterna.

Passo 4: Richiesta API e parsing della risposta

Mettiamo tutto insieme. Costruiamo l'URL sostituendo ID e chiave, effettuiamo una richiesta GET e decodifichiamo il JSON:

1
<?php
2
 
3
$apiKey   = 'AIzaSyD-YOUR_KEY';
4
$videoUrl = 'https://www.youtube.com/watch?v=1ejTKov_Sm4';
5
$videoId  = getYouTubeVideoId($videoUrl);
6
 
7
if (!$videoId) {
8
    die('Failed to extract video ID from URL.');
9
}
10
 
11
$endpoint = sprintf(
12
    'https://www.googleapis.com/youtube/v3/videos?part=snippet,contentDetails,statistics&id=%s&key=%s',
13
    $videoId,
14
    $apiKey
15
);
16
 
17
// Option with file_get_contents (requires allow_url_fopen = On in php.ini)
18
$context = stream_context_create([
19
    'http' => [
20
        'timeout'        => 10,
21
        'ignore_errors'  => true, // do not crash on HTTP errors
22
    ],
23
]);
24
 
25
$response = @file_get_contents($endpoint, false, $context);
26
 
27
if ($response === false) {
28
    die('Network request failed. Check your connection or use cURL.');
29
}
30
 
31
$data = json_decode($response);
32
 
33
if (json_last_error() !== JSON_ERROR_NONE) {
34
    die('API response is not JSON. The key might be invalid.');
35
}
36
 
37
// API returns error in error field, not HTTP status
38
if (isset($data->error)) {
39
    die('API Error: ' . $data->error->message);
40
}
41
 
42
if (empty($data->items)) {
43
    die('No video found with this ID.');
44
}
45
 
46
$video = $data->items[0];
47
 
48
echo 'Title: ' . $video->snippet->title . PHP_EOL;
49
echo 'Channel: ' . $video->snippet->channelTitle . PHP_EOL;
50
echo 'Published: ' . $video->snippet->publishedAt . PHP_EOL;
51
echo 'Duration: ' . $video->contentDetails->duration . PHP_EOL;
52
echo 'Views: ' . number_format($video->statistics->viewCount ?? 0) . PHP_EOL;
53
echo 'Likes: ' . number_format($video->statistics->likeCount ?? 0) . PHP_EOL;
54
echo 'Comments: ' . number_format($video->statistics->commentCount ?? 0) . PHP_EOL;
55
 
56
// Max resolution thumbnail URL
57
if (isset($video->snippet->thumbnails->maxres)) {
58
    echo 'Thumbnail: ' . $video->snippet->thumbnails->maxres->url . PHP_EOL;
59
}

Il codice è sensibilmente più robusto di un semplice file_get_contents() di una bozza. Aggiunti: controllo estrazione ID, gestione errori di rete, validazione JSON, risposta all'errore API Google (il campo error), controllo risposta vuota e operatore di fallback ?? per i campi statistici opzionali.

CURL come alternativa

Se la direttiva allow_url_fopen è disabilitata sul tuo hosting, file_get_contents() non funzionerà. In tal caso, usa cURL:

1
$ch = curl_init();
2
curl_setopt_array($ch, [
3
    CURLOPT_URL            => $endpoint,
4
    CURLOPT_RETURNTRANSFER => true,
5
    CURLOPT_TIMEOUT        => 10,
6
    CURLOPT_FOLLOWLOCATION => true,
7
]);
8
$response = curl_exec($ch);
9
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
10
curl_close($ch);
11
 
12
if ($httpCode !== 200 || $response === false) {
13
    die('Request failed. HTTP code: ' . $httpCode);
14
}

Libreria già pronta: madcoda/php-youtube-api

Scrivere un wrapper a mano per la produzione è lavoro extra. Per progetti che necessitano di interazione regolare con l'API anziché un recupero una tantum, esiste madcoda/php-youtube-api, un wrapper PHP leggero senza dipendenze esterne. Installazione:

1
composer require madcoda/php-youtube-api

Utilizzo:

1
$youtube = new Madcoda\Youtube(['key' => 'YOUR_KEY']);
2
$video   = $youtube->getVideoInfo('1ejTKov_Sm4');
3
 
4
echo $video->snippet->title;
5
echo $video->statistics->viewCount;

La libreria gestisce le attività di routine: paginazione, tentativi di richiesta, formattazione della durata da ISO 8601 a un formato leggibile. Per script occasionali è sproporzionata; per un servizio operativo è giustificata.

La video guida qui sopra mostra chiaramente l'intero processo: dall'abilitazione dell'API nella console alla prima richiesta riuscita. Consigliamo di guardarlo prima di scrivere codice: 15 minuti di video fanno risparmiare un'ora di lettura della documentazione.

⁉️🤔 Domande frequenti

Quanto costa usare YouTube Data API?

L'API in sé è gratuita. Paghi solo in quota: 10.000 unità al giorno per ogni progetto. Una richiesta a /videos costa 1 unità, quindi puoi ottenere dati su 10.000 video al giorno senza spendere un centesimo. Per progetti commerciali con carico superiore alla soglia, Google offre un modulo di richiesta aumento quota; lo approvano con una motivazione adeguata. YouTube Data API non ha livelli a pagamento separati.

In cosa si differenzia YouTube Data API v3 dal parsing della pagina HTML?

L'API restituisce JSON strutturato con uno schema documentato. Quando i campi cambiano, Google pubblica un avviso di deprecazione con diversi mesi di anticipo. Il parsing HTML si rompe a ogni riprogettazione della pagina, richiede l'emulazione del browser ed è esplicitamente vietato dalla sezione 3.2 dei Termini di servizio di YouTube.

Posso ottenere dati su un video privato?

Con una chiave API, solo video pubblici. Per l'accesso a video privati, non in elenco e con restrizioni, è richiesto OAuth 2.0 con il permesso del proprietario. Tecnicamente è lo stesso endpoint /videos, ma con un token di accesso invece di una chiave.

Come ottengo l'ID del mio canale YouTube?

Il modo più affidabile: YouTube Studio → Impostazioni → Canale → Impostazioni avanzate. Lì l'ID canale YouTube viene mostrato così com'è, senza richieste API. In alternativa: chiama /channels?part=id&mine=true con un token OAuth. Per canali con nome utente personalizzato, il metodo /channels?part=id&forUsername=NAME funziona solo per quelli creati prima del 2014.

Cosa devo fare quando ricevo un errore "quotaExceeded"?

La quota giornaliera si azzera alle 00:00 ora del Pacifico (UTC-8). Soluzione temporanea: memorizza le risposte nella cache lato tuo (file, Redis). Per un aumento permanente: Google Cloud Console → IAM e amministrazione → Quote → YouTube Data API v3 → richieste al giorno → Modifica quota.

Dove applicare YouTube Data API: riepilogo finale

Abbiamo coperto l'intero ciclo: chiave API, analisi dei parametri dell'endpoint, estrazione ID video dall'URL, richiesta GET e parsing della risposta JSON. Il risultato è uno script PHP funzionante che recupera titolo, statistiche, durata e miniature di qualsiasi video pubblico in un secondo.

Dove andare dopo:

• Schede video su un sito web. Integra lo script in un backend WordPress (hook save_post) o Laravel, e quando aggiungi un link YouTube, le informazioni del video vengono recuperate automaticamente.
• Monitoraggio della concorrenza. Una volta al giorno, raccogli viewCount e likeCount per un elenco di canali e la tua tabella delle dinamiche è pronta.
• Importazione automatica. Se gestisci un video blog sul tuo sito, recupera snippet.title e snippet.description come bozza di descrizione testuale per l'incorporamento.

YouTube Data API v3 è uno strumento maturo, stabile e gratuito. Avendo padroneggiato la chiamata di base di questo tutorial, apri la porta a dozzine di altri metodi: ricerca, playlist, commenti, iscrizioni. 🔗 Documentazione ufficiale YouTube Data API v3