📹 Analisar dados de vídeos do YouTube sem HTML: API v3 e PHP (guia 2026)

Porquê analisar dados de vídeo via API quando pode simplesmente abrir a página?

Recolher manualmente informações sobre dezenas de vídeos demora horas. Título, duração, contagem de visualizações, data de publicação: copiar tudo isto à mão do YouTube é um caminho garantido para erros e esgotamento.

A API YouTube Data v3 resolve o problema de forma programática. Um pedido HTTP e obtém JSON estruturado com snippet, contentDetails e statistics. Sem parsing de HTML, sem captchas.

Neste tutorial: instruções passo a passo, desde a criação de uma chave de API até um script PHP pronto a usar que extrai informações de qualquer vídeo do YouTube pelo seu URL. O código é real, testado, com explicações para cada linha.

💡 Resumo rápido:

Criar uma chave de API no Google Cloud Console e ativar a YouTube Data API v3
Analisar a estrutura do endpoint /videos e os seus parâmetros part, id e key
Escrever uma função PHP para extrair o ID do vídeo de qualquer link do YouTube
Fazer um pedido via file_get_contents() e analisar a resposta JSON
Tratar erros: chave inválida, ID errado, quota excedida
Ver uma alternativa: a biblioteca pronta a usar madcoda/php-youtube-api

Passo 1: Obter uma chave da API YouTube Data

Para trabalhar com a API, precisa de uma chave. Aqui está o caminho mais curto:

Abra a Google Cloud Console e crie um novo projeto (ou selecione um existente).
Vá a APIs & Services → Library, encontre "YouTube Data API v3" e clique em Enable.
Vá a Credentials → Create Credentials → API Key.
(Recomendado) Restrinja a chave: na secção API restrictions, selecione YouTube Data API v3 para que a chave não funcione com outros serviços da Google.

A chave tem o aspeto de uma string como AIzaSyD-... com 39 caracteres. Sem ela, a API devolve um erro 403.

A quota diária é de 10.000 unidades. Um pedido a /videos custa 1 unidade. Para testes e pequenos projetos, isto é mais do que suficiente. Se estiver a planear uma carga de nível de produção, solicite um aumento de quota na mesma secção da Console.

Passo 2: Endpoint da API e seus parâmetros

URL para obter informações do vídeo:

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

Os parâmetros são passados como query string:

Parâmetro	Obrigatório	Descrição
`part`	Sim	Lista de campos separados por vírgulas: snippet, contentDetails, statistics, status, topicDetails, etc.
`id`	Sim	ID do vídeo do YouTube (11 caracteres, ex.: `1ejTKov_Sm4`)
`key`	Sim	A sua chave de API
`hl`	Não	Idioma para campos de texto (ex.: `ru` para títulos em russo)
`maxResults`	Não	Número de resultados (1-50, o padrão é 5)

Três valores principais de part que cobrem a maioria dos cenários:

snippet: informações básicas: título, descrição, channelId, channelTitle, publishedAt, thumbnails (conjunto de URLs de miniaturas em diferentes resoluções), tags, categoryId.
contentDetails: características: duração (em formato ISO 8601, ex.: PT4M13S), dimension (2d/3d), definition (sd/hd), caption (se existem legendas).
statistics: números: viewCount, likeCount, commentCount.

Nota importante: o campo dislikeCount nas statistics foi desativado desde dezembro de 2021, a API devolve sempre 0. O campo favoriteCount também está obsoleto (sempre 0 desde agosto de 2015). Não confie neles no seu código.

Passo 3: Extrair o ID do vídeo do URL

Antes de chamar a API, precisa de extrair o ID do vídeo do link. O YouTube tem vários formatos de URL:

Padrão: https://www.youtube.com/watch?v=1ejTKov_Sm4
Curto: https://youtu.be/1ejTKov_Sm4
Incorporado: https://www.youtube.com/embed/1ejTKov_Sm4
Com parâmetros: https://www.youtube.com/watch?v=1ejTKov_Sm4&t=120

Uma função PHP simples trata todas estas variantes:

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

A função usa apenas capacidades nativas do PHP: parse_url() divide o URL em componentes, parse_str() analisa a query string para um array. Sem dependências externas.

Passo 4: Pedido à API e parsing da resposta

Juntando tudo. Construímos o URL substituindo o ID e a chave, fazemos um pedido GET e descodificamos o 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 }

O código é notoriamente mais robusto do que um simples file_get_contents() de uma versão de rascunho. Adicionado: verificação da extração do ID, tratamento de erros de rede, validação de JSON, resposta a erro da API da Google (o campo error), verificação de resposta vazia e operador de fallback ?? para campos de estatísticas opcionais.

CURL como alternativa

Se a diretiva allow_url_fopen estiver desativada no seu alojamento, o file_get_contents() não funcionará. Nesse caso, use 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 }

Biblioteca pronta a usar: madcoda/php-youtube-api

Escrever um wrapper manualmente para produção é trabalho extra. Para projetos que precisam de interação regular com a API, em vez de uma consulta única, existe a madcoda/php-youtube-api, um wrapper PHP leve sem dependências externas. Instalação:

1 composer require madcoda/php-youtube-api

Utilização:

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;

A biblioteca trata de tarefas rotineiras: paginação, novas tentativas de pedidos, formatação da duração de ISO 8601 para um formato legível. Para scripts pontuais, é um exagero; para um serviço em funcionamento, justifica-se.

O guia em vídeo acima mostra claramente todo o processo: desde a ativação da API na consola até ao primeiro pedido bem-sucedido. Recomendamos que o veja antes de escrever código: 15 minutos de vídeo poupam uma hora de leitura de documentação.

Código PHP num ecrã de monitor em grande plano

⁉️🤔 Perguntas frequentes

Quanto custa usar a YouTube Data API?

A API em si é gratuita. Paga-se apenas com quota: 10.000 unidades por dia para cada projeto. Um pedido a /videos custa 1 unidade, portanto pode obter dados sobre 10.000 vídeos diariamente sem gastar um cêntimo. Para projetos comerciais com carga acima do limite, a Google oferece um formulário de pedido de aumento de quota; aprovam-no com uma justificação adequada. A YouTube Data API não tem escalões pagos separados.

Em que é que a YouTube Data API v3 difere do parsing de páginas HTML?

A API devolve JSON estruturado com um esquema documentado. Quando os campos mudam, a Google publica um aviso de depreciação com vários meses de antecedência. O parsing de HTML quebra com qualquer redesenho da página, requer emulação de navegador e é explicitamente proibido pela secção 3.2 dos Termos de Serviço do YouTube.

Posso obter dados sobre um vídeo privado?

Com uma chave de API, apenas vídeos públicos. Para acesso a vídeos privados, não listados e restritos, é necessário OAuth 2.0 com permissão do proprietário. Tecnicamente, é o mesmo endpoint /videos, mas com um token de acesso em vez de uma chave.

Como obtenho o ID do meu canal do YouTube?

A forma mais fiável: YouTube Studio → Definições → Canal → Definições avançadas. Aí, o ID do canal do YouTube é mostrado tal como é, sem quaisquer pedidos à API. Alternativamente: chame /channels?part=id&mine=true com um token OAuth. Para canais com nomes de utilizador personalizados, o método /channels?part=id&forUsername=NAME só funciona para os criados antes de 2014.

O que devo fazer quando recebo um erro "quotaExceeded"?

A quota diária é reposta às 00:00, hora do Pacífico (UTC-8). Solução temporária: coloque as respostas em cache do seu lado (ficheiro, Redis). Para um aumento permanente: Google Cloud Console → IAM & Admin → Quotas → YouTube Data API v3 → pedidos por dia → Edit Quota.

Onde aplicar a YouTube Data API: resumo final

Cobrimos o ciclo completo: chave de API, detalhe dos parâmetros do endpoint, extração do ID do vídeo do URL, pedido GET e parsing da resposta JSON. O resultado é um script PHP funcional que obtém o título, estatísticas, duração e miniaturas de qualquer vídeo público num segundo.

Para onde seguir a seguir:

Fichas de vídeo num site. Integre o script num backend WordPress (hook save_post) ou Laravel, e ao adicionar um link do YouTube, a informação do vídeo é obtida automaticamente.
Monitorização da concorrência. Uma vez por dia, recolha viewCount e likeCount para uma lista de canais, e a sua tabela de dinâmicas está pronta.
Importação automática. Se gere um blog de vídeo no seu próprio site, obtenha snippet.title e snippet.description como um rascunho de descrição de texto para incorporação.

A YouTube Data API v3 é uma ferramenta madura, estável e gratuita. Tendo dominado a chamada básica deste tutorial, abre a porta a dezenas de outros métodos: pesquisa, listas de reprodução, comentários, subscrições. 🔗 Documentação oficial da YouTube Data API v3

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

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	}

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	}

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;

Tudo para WordPress, desenvolvimento web — e não só

📹 YouTube Data API v3: obter dados de vídeos com PHP (2026)