Esta página mostra exemplos de solicitações para a API de dados do YouTube. Você usa a API YouTube Data para recuperar e manipular recursos do YouTube, como vídeos, canais e playlists. Cada amostra é vinculada e preenche o Google APIs Explorer para que você possa executá-la e ver a resposta.
Para saber mais sobre o envio de conteúdo usando a API YouTube Data, consulte Uploads retomáveis.
Visão geral
Para facilitar a apresentação, as amostras nesta página mostram os elementos distintos de cada solicitação e abreviam o URL base para o host que processa as solicitações da API de dados (https://www.googleapis.com/youtube/v3). Para fazer a solicitação fora do contexto das amostras, é preciso incluir o URL completo.
Por exemplo, veja um exemplo de solicitação, conforme mostrado nesta página:
GET {base-URL}/channels?part=contentDetails &mine=true
O URL completo para essa solicitação é:
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Várias das solicitações recuperam dados acessíveis apenas ao proprietário do canal do YouTube, como a lista de inscritos. Essas solicitações exigem que o proprietário do canal conceda ao APIs Explorer do Google o direito de realizar solicitações da API de dados do YouTube em nome dele. Consulte Como implementar a autenticação do OAuth 2.0 para ver detalhes sobre como autorizar o acesso a dados de canais privados. Depois de vincular ao APIs Explorer, clique no botão Autorizar solicitações usando o OAuth 2.0. Esta etapa autoriza o APIs Explorer a fazer solicitações em nome do proprietário. Você também seleciona o escopo da autorização, que especifica os tipos de solicitações que o APIs Explorer pode realizar.
A resposta para cada solicitação é a representação JSON de um recurso do YouTube. O parâmetro part na solicitação especifica quais partes do recurso são incluídas na resposta. O parâmetro identifica uma ou mais propriedades de recursos de nível superior (não aninhadas) que devem ser incluídas na resposta. Por exemplo, algumas partes de um recurso video são:
- snippet
- Detalhes do conteúdo
- jogador
- statistics
- status
Todas essas partes são objetos que contêm propriedades agrupadas, e esses objetos são considerados grupos de campos de metadados que podem (ou não) ser recuperados pelo servidor da API. Por isso, o parâmetro part exige que você selecione os componentes do recurso que seu app realmente usa.Para mais informações, consulte Introdução à API de dados do YouTube.
Recuperar informações do canal
Essa solicitação usa o método channels.list para recuperar detalhes sobre os canais que pertencem ao usuário autenticado.
GET {base_URL}/channels?part=contentDetails &mine=true
A resposta a essa solicitação inclui o ID do canal e o contentDetails para o canal do usuário autenticado. O contentDetails inclui as várias playlists geradas pelo sistema associadas ao canal. Muitas das solicitações seguintes exigem o ID do canal ou um dos IDs de playlist, por isso é importante registrá-los.
{
"id": {CHANNEL_ID},
"kind": "youtube#channel",
"etag": etag,
"contentDetails": {
"relatedPlaylists": {
"likes": {LIKES_PLAYLIST_ID},
"favorites": {FAVORITES_PLAYLIST_ID},
"uploads": {UPLOADS_PLAYLIST_ID},
"watchHistory": {WATCHHISTORY_PLAYLIST_ID},
"watchLater": {WATCHLATER_PLAYLIST_ID}
},
"googlePlusUserId": string
},
}
Vídeos enviados e playlists geradas pelo sistema
O YouTube adiciona todos os vídeos enviados a uma playlist associada ao canal. Para acessar a lista dos vídeos enviados, consulte a playlist "Envios" retornada na resposta mostrada acima para ver as informações do canal. Use o método playlistItems.list para recuperar os vídeos dessa playlist.
Antes de executar a seguinte solicitação de exemplo no Google APIs Explorer, substitua {UPLOADS_PLAYLIST_ID} pelo ID da playlist da solicitação anterior.
GET {base_URL}/playlistItems?part=contentDetails &playlistId={UPLOADS_PLAYLIST_ID}
O valor "id" de cada item retornado é o ID da playlistItem. O ID do vídeo do item da playlist é o videoId na parte contentDetails.
Você pode recuperar os favoritos, as marcações "Gostei" e o histórico de exibição de um usuário usando a solicitação acima substituindo o ID da playlist correspondente na resposta de informações do canal.
Playlists criadas pelo usuário
Essa solicitação usa o método playlists.list para recuperar as playlists associadas ao canal autenticado. Essa solicitação não recupera as playlists geradas pelo sistema incluídas nas informações do canal (uploads, watchHistory e assim por diante). Ela recupera apenas playlists criadas pelo usuário.
GET {base_URL}/playlists?part=snippet &mine=true
Com um ID da playlist, é possível recuperar os itens da playlist usando a solicitação mostrada na seção anterior.
Você pode solicitar informações sobre as playlists públicas de um canal sem autenticação. Ao enviar uma solicitação não autenticada, é necessário incluir o argumento key que especifica a chave de API exclusiva do aplicativo que está fazendo a solicitação. Por exemplo, essa solicitação recupera as playlists associadas ao canal GoogleDevelopers.
GET {base_URL}/playlists?part=snippet &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw &key={YOUR_API_KEY}
Recuperar assinaturas
Um recurso subscription define uma relação entre um usuário do YouTube (o assinante) e um canal. O método subscriptions.list recupera os assinantes de um canal específico ou as assinaturas de um usuário específico, dependendo de quais parâmetros você inclui na solicitação.
Inscritos no canal
Essa solicitação recupera uma lista de inscritos no canal autenticado.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Assinaturas de usuário
O mesmo método que lista os inscritos (subscriptions.list) pode ser usado para listar os canais em que um usuário se inscreveu. Essa solicitação usa o parâmetro mine para recuperar uma lista dos canais do YouTube em que o usuário autenticado se inscreveu.
GET {base_URL}/subscriptions?part=snippet &mine=true
Recuperar atividade do usuário
Um recurso activity contém informações sobre uma ação que um determinado canal ou usuário realizou no YouTube, como o envio de um vídeo, a inscrição em um canal e assim por diante. O método activities.list recupera as ações associadas a um canal ou usuário que correspondem aos critérios da solicitação. Por exemplo, você pode recuperar ações associadas a um canal específico, com as inscrições do usuário ou com a página inicial personalizada do YouTube do usuário.
Atividade durante um período
Essa solicitação recupera todas as ações que o usuário autenticado realizou durante abril de 2013.
GET {base_URL}/activities?part=snippet,contentDetails &mine=true &publishedAfter=2013-04-01T00%3A00%3A00Z &publishedBefore=2013-05-01T00%3A00%3A00Z
Atividade da página inicial
Essa solicitação recupera o feed de atividades personalizado exibido na página inicial do YouTube do usuário autenticado.
GET {base_URL}/activities?part=snippet,contentDetails &home=true
Para recuperar estatísticas de visualização, métricas de popularidade e informações demográficas para vídeos e canais do YouTube, use a API YouTube Analytics. A página Solicitações da API de exemplo mostra como recuperar relatórios comuns do YouTube Analytics.
Pesquisa
O método search.list permite pesquisar vídeos, canais ou playlists do YouTube que correspondam aos critérios especificados. É possível pesquisar com base em propriedades de vídeo, palavras-chave ou tópicos (ou uma combinação destes) e classificar os resultados com base em fatores como data de criação, contagem de visualizações ou classificação.
Assim como outras solicitações da API YouTube Data, o método search.list retorna a representação JSON de um recurso do YouTube. Diferentemente de outros recursos do YouTube, no entanto, um resultado da pesquisa não é um objeto persistente com um ID exclusivo.
Muitas solicitações pesquisam conteúdo disponível publicamente e, portanto, não exigem autenticação. Entre os exemplos abaixo, somente o primeiro exige autenticação, já que ele solicita especificamente meus vídeos. Ao enviar uma solicitação não autenticada, é necessário incluir o argumento key que especifica a chave de API exclusiva do seu aplicativo.
Meus vídeos mais assistidos
Essa solicitação recupera todos os vídeos do usuário autenticado e os lista em ordem decrescente por contagem de visualizações.
GET {base_URL}/search?part=snippet &forMine=true &order=viewCount &type=video
Vídeos incorporáveis em alta definição
Essa solicitação procura vídeos que têm propriedades específicas, ou seja, vídeos de alta definição que podem ser incorporados em outros sites. Ele lista os resultados em ordem decrescente de classificação.
GET {base_URL}/search?part=snippet &order=rating &type=video &videoDefinition=high &videoEmbeddable=true &key={YOUR_API_KEY}
Vídeos sobre um assunto específico
Esta solicitação realiza uma pesquisa de palavra-chave para vídeos sobre a API de dados do YouTube que incluem legendas.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Pesquisa baseada em tópicos
Uma maneira mais sofisticada de pesquisar vídeos sobre um determinado assunto é usar tópicos do Freebase em vez de palavras-chave. Todos os recursos de vídeo e canal do YouTube têm um objeto topicDetails com uma lista de IDs de tópicos do Freebase associados ao recurso. Uma pesquisa com base em tópicos é mais inteligente do que uma pesquisa de palavras-chave, porque um tópico do Freebase representa todos os aspectos de um conceito ou item do mundo real.
Para pesquisar usando um tópico do Freebase, primeiro você precisa recuperar o ID do tópico usando a API Freebase. Esta solicitação retorna vídeos associados ao tópico do Freebase para Python, cujo ID do tópico é /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Como pesquisar playlists ou canais
A pesquisa não se limita a vídeos. Também é possível pesquisar playlists ou canais. Essa solicitação recupera playlists que correspondem à palavra-chave "soccer".
GET {base_URL}/search?part=snippet &q=soccer &type=playlist &key={YOUR_API_KEY}
Se preferir encontrar canais de futebol, altere o parâmetro type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Se você quiser todo o conteúdo relacionado a futebol (canais, playlists e vídeos), faça uma pesquisa universal. Se você omitir o parâmetro type, a solicitação vai recuperar conteúdo de todos os tipos
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Criar e atualizar recursos
Todas as solicitações que vimos até agora usam o método HTTP GET para recuperar dados do YouTube. A API de dados do YouTube também oferece métodos que usam HTTP POST para criar ou atualizar recursos do YouTube, como vídeos, playlists ou canais. As solicitações a seguir fornecem exemplos.
Os métodos POST incluem um Request body, que é a representação JSON do recurso que está sendo criado ou atualizado. Você pode criar representações JSON no APIs Explorer do Google usando uma ferramenta interativa.
Crie uma assinatura
Esta solicitação inscreve o usuário autenticado no canal GoogleDevelopers. Em outras palavras, ele cria um recurso de assinatura.
POST {base_URL}/subscriptions?part=snippet
Request body: { 'snippet': { 'resourceId': { 'kind': 'youtube#channel', 'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' } } }
Criar uma playlist
Esta solicitação cria uma nova playlist pública.
POST {base_URL}/playlists?part=snippet
Request body: { 'snippet': { 'title': 'New playlist', 'description': 'Sample playlist for Data API', } }
Adicionar um vídeo a uma lista de reprodução
Agora que já criamos uma playlist, vamos adicionar um vídeo a ela. Esta solicitação adiciona um vídeo ao início da playlist ('position': 0).
POST {base_URL}/playlistItems?part=snippet Request body: { 'snippet': { 'playlistId': '{PLAYLIST_ID}', 'resourceId': { 'kind': 'youtube#video', 'videoId': '{VIDEO_ID}' } 'position': 0 } }