O seu site precisa de um feed de vídeos do YouTube, mas não existe um plugin pronto para a tarefa e já está a imaginar uma semana a lutar com OAuth, tokens e bibliotecas desajeitadas. A API de Dados do YouTube v3 resolve isto em cerca de uma hora. Sem OAuth, sem tokens de utilizador, sem dependências externas. Apenas uma chave de API e um URL corretamente construído.

O endpoint de pesquisa devolve vídeos, canais e listas de reprodução por palavras-chave. Filtra por data, duração e canal. Ordena por relevância ou número de visualizações. Na prática, isto cobre a maioria dos cenários, desde o feed de vídeos de um canal específico até uma compilação de "tutoriais de wordpress" do último mês.

Abaixo encontra um guia passo a passo com exemplos de pedidos ao vivo e código PHP. No final, terá um módulo de pesquisa funcional: JSON estruturado a entrar, galeria de vídeos a sair, zero bibliotecas de terceiros.

💡 Visão geral rápida:

• Crie um projeto na consola Google Cloud, ative a API de Dados do YouTube v3 e obtenha uma chave de API.
• Construa o URL do pedido de pesquisa: endpoint /youtube/v3/search, parâmetros obrigatórios part=snippet, key e q (desde junho de 2025, q é obrigatório; sem ele, a API devolve um array vazio).
• Adicione filtros: type (video/channel/playlist), channelId, publishedAfter/publishedBefore, maxResults, order, videoDuration, videoEmbeddable.
• Execute o pedido via cURL em PHP, analise a resposta JSON, mostre os resultados e configure a cache através de transients do WordPress.

Passo 1: Obter a sua chave de API

Sem chave, não há pedido de API que funcione. A chave está associada a um projeto na Consola Google Cloud e identifica a sua aplicação; não é necessário nada mais complicado do que iniciar sessão numa conta Google.

Eis o que deve fazer:

• Abra a Consola Google Cloud e crie um novo projeto ou selecione um existente.
• Vá a APIs e Serviços → Biblioteca, pesquise por "YouTube Data API v3" e clique em Ativar.
• Abra APIs e Serviços → Credenciais, clique em Criar Credenciais → Chave de API.
• Copie a chave. Defina imediatamente uma restrição: Restringir Chave → YouTube Data API v3, para que a chave não possa ser usada noutros serviços Google.

A chave tem o aspeto de uma string como AIzaSyD-... e é passada em cada pedido através do parâmetro key. Para pesquisa de vídeos públicos, isto é suficiente; não é necessário OAuth. No entanto, se planear fazer pedidos em nome de um utilizador (carregamento de vídeos, gestão de listas de reprodução), precisará de OAuth 2.0.

Teste rápido: envie um pedido GET para o endpoint search com qualquer termo de pesquisa. Se receber JSON com um array items, a chave funciona.

Passo 2: URL do pedido de pesquisa e parâmetros obrigatórios

Endpoint para pesquisa:

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

Dois parâmetros são sempre obrigatórios:

O parâmetro q aceita texto livre, tal como a barra de pesquisa em youtube.com. Pode passar várias palavras separadas por espaços ou sinais de mais: q=wordpress+speed+optimization. Maiúsculas e minúsculas são indiferentes.

Pedido mínimo funcional:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress&key=YOUR_KEY

Devolverá 5 resultados (o padrão), que é o que a API devolve quando maxResults não é substituído.

O parâmetro type restringe o tipo de recurso a ser pesquisado:

• video, apenas vídeos;
• channel, apenas canais;
• playlist, apenas listas de reprodução.

Pode listar vários valores separados por vírgulas: type=video,channel. Se omitido, a API pesquisa tudo. Os restantes parâmetros são opcionais, mas transformam uma consulta bruta numa ferramenta precisa.

Passo 3: Pesquisar vídeos por palavras-chave

Um cenário clássico: um utilizador introduz uma frase de pesquisa no seu site, envia-a para a API do YouTube e você mostra uma seleção de vídeos.

Exemplo de pedido para pesquisar vídeos com a palavra "swimming":

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=swimming&type=video&key=YOUR_KEY

A resposta vem em JSON. Dentro de items[] está um array de recursos encontrados. Para cada vídeo, tem:

• id.videoId, o identificador único (usado em https://www.youtube.com/watch?v=...);
• snippet.title, o título do vídeo;
• snippet.description, a descrição;
• snippet.thumbnails, pré-visualizações em várias resoluções (default, medium, high);
• snippet.channelTitle, o nome do canal.

Em PHP, a forma mais fácil de obter a resposta é via file_get_contents. Aqui está um código de processamento mínimo:

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 é adequado para testes e projetos pequenos. Em produção, use cURL: dá-lhe controlo sobre timeouts, cabeçalhos e tratamento de erros. E sim, se allow_url_fopen estiver desativado no seu alojamento, file_get_contents não funcionará para URLs externos. Nesse caso, o cURL é a sua única opção.

Passo 4: Obter vídeos de um canal específico

Para recolher todos os vídeos de um canal, passe o parâmetro channelId. Encontrar o identificador do canal é fácil: abra a página do canal no YouTube e copie o valor após /channel/ da barra de endereço (por exemplo UC3VyA8KN_VgCF93EurnAQXw).

Pedido:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UC3VyA8KN_VgCF93EurnAQXw&type=video&order=date&key=YOUR_KEY

O parâmetro order=date ordena por data de publicação, do mais recente para o mais antigo. Sem ele, a API devolve os resultados mais relevantes, mas para um feed de canal, a ordem cronológica faz mais sentido.

O mesmo pedido em PHP com cURL e tratamento básico de erros:

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
}

Um canal pode ter centenas de vídeos, mas um único pedido não devolve mais de 50. Para obter tudo, use o campo pageToken da resposta da API: passe o seu valor no pedido seguinte como pageToken=<token>. Repita até que nextPageToken esteja vazio.

Passo 5: Limites, ordenação e quotas

Num site real, raramente precisa de "todos os vídeos para uma consulta". Mais frequentemente, quer o top 10 do último mês ou uma seleção que exclua Shorts. Para isso, a API fornece cinco parâmetros de ajuste fino.

maxResults: quantos itens devolver. Valores válidos: 1 a 50. O padrão é 5. Para uma galeria ou feed, defina 20-30, mas tenha as quotas em mente.

order: campo de ordenação:

publishedAfter** / **publishedBefore: filtrar por data de publicação. Formato: ISO 8601 (RFC 3339). Exemplo: publishedAfter=2026-01-01T00:00:00Z. Elimina vídeos arquivados quando só precisa de conteúdo recente.

videoDuration: filtrar por duração:

• short, menos de 4 minutos;
• medium, de 4 a 20 minutos;
• long, mais de 20 minutos;
• não especificado, todos.

videoEmbeddable com o valor true seleciona apenas vídeos cuja incorporação é permitida em sites de terceiros. Para um site que incorpora o leitor do YouTube, este é um parâmetro obrigatório.

Pedido combinado: 10 vídeos incorporáveis sobre WordPress, não anteriores a 2026, com mais de 4 minutos, ordenados por número de visualizações:

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

Quotas: como evitar um ecrã em branco

Cada chamada search.list custa 100 unidades da sua quota diária. Por padrão, um projeto Google Cloud recebe 10 000 unidades por dia gratuitamente, cerca de 100 chamadas de pesquisa. Para um site com mais de cem visitantes por dia, isso não é suficiente.

A solução é colocar em cache as respostas da API. No WordPress, os transients funcionam perfeitamente para isto:

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...

Um transient de seis horas significa um máximo de 4 pedidos à API por dia para uma única frase de pesquisa. Mesmo com dez consultas diferentes nas páginas do site, fica abaixo de 40 chamadas, menos de metade da quota diária. Se precisar de mais, solicite um aumento de quota através da Consola Google Cloud: Quotas → YouTube Data API v3 → Editar.

O exemplo ao vivo acima mostra como construir uma galeria de vídeos de um canal via API de Dados v3 em PHP em 15 minutos.

⁉️🤔 Perguntas frequentes

É necessário OAuth para pesquisar vídeos através da API do YouTube?

Não. Para pedidos de pesquisa a /youtube/v3/search, uma chave de API é suficiente. OAuth é necessário apenas para operações ao nível do utilizador: carregar vídeos, gerir listas de reprodução, subscrições. Uma chave de API obtém-se na Consola Google Cloud em poucos minutos e é usada de imediato.

Quantos pedidos por dia podem ser feitos gratuitamente?

Cada projeto Google Cloud recebe 10 000 unidades de quota por dia gratuitamente. Uma chamada search.list custa 100 unidades, portanto, cerca de 100 pedidos de pesquisa por dia. Com cache via transients do WordPress, isto é suficiente para um site médio. Se precisar de mais, solicite um aumento de quota através da Consola Google Cloud (secção Quotas).

Como obtenho mais de 50 resultados de uma única consulta?

Através de paginação. Na resposta JSON, a API devolve um campo nextPageToken. Passe o seu valor como o parâmetro pageToken no pedido seguinte para obter a página seguinte. Repita até que nextPageToken esteja vazio. Uma passagem completa por um canal com 500 vídeos requer 10 pedidos e 1 000 unidades de quota.

Posso pesquisar vídeos em idiomas diferentes do inglês?

Sim. O parâmetro q aceita qualquer idioma, incluindo russo. O algoritmo de pesquisa do YouTube determina automaticamente a relevância do idioma. Para forçar um filtro, adicione o parâmetro relevanceLanguage=ru; os resultados serão classificados a favor de conteúdo em russo.

Porque é que a API devolve um array vazio mesmo que o pedido esteja correto?

A causa mais comum: publishedAfter está definido para uma data futura ou para a data de hoje com uma hora exata. Use o início do dia: T00:00:00Z. A segunda causa: uma combinação de filtros que exclui todos os resultados. Por exemplo, videoDuration=long e videoEmbeddable=true juntamente com o channelId de um canal pequeno pode resultar em zero correspondências. Simplifique o pedido para part=snippet&q=...&key=... e adicione os filtros um de cada vez, verificando os resultados a cada passo.

Construir pesquisa numa hora: que ferramentas se adequam a cada tarefa

A sua escolha de ferramentas depende exatamente do que está a construir. Se precisa de uma galeria de vídeos simples para um canal num site de pequena empresa, use um wrapper PHP pronto como madcoda/php-youtube-api: um pacote Composer, três linhas de código, resultado em cinco minutos. Se está a construir uma pesquisa personalizada com filtros, cache e paginação, escreva o seu próprio manipulador usando cURL e transients do WordPress. Para um site de alto tráfego com dezenas de milhares de visitantes, adicione uma camada de cache Redis sobre os transients e configure a sincronização em segundo plano via WP-Cron; assim, as páginas carregam em milissegundos e as quotas da API são gastas apenas na invalidação da cache.

Já tem a sua chave de API. A cache está configurada. Só falta montar o URL para a sua tarefa e escrever o ciclo de saída. O resultado é um feed de vídeos ao vivo que não depende de serviços de terceiros e não atinge os limites de quota.