Esta página mostra exemplos de solicitações para a API YouTube Data. Você usa a API de dados do YouTube para recuperar e manipular recursos do YouTube, como vídeos, canais e playlists. Cada exemplo é vinculado a e preenche o Google APIs Explorer para que você possa executar o exemplo e ver a resposta.
Para mais informações sobre o envio de conteúdo pela API YouTube Data, consulte Envios retomáveis.
Visão geral
Para fins de clareza da apresentação, os exemplos nesta página mostram os elementos distintos de cada solicitação e abreviam o URL de base do host que processa as solicitações da API Data (https://www.googleapis.com/youtube/v3). Para fazer a solicitação fora do contexto das amostras, inclua o URL completo.
Por exemplo, aqui está um exemplo de solicitação como aparece nesta página:
GET {base-URL}/channels?part=contentDetails &mine=true
O URL completo da solicitação é:
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Várias das solicitações recuperam dados que só podem ser acessados pelo 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 YouTube Data em nome dele. Consulte Como implementar a autenticação OAuth 2.0 para detalhes sobre como autorizar o acesso a dados de canais privados. Após vincular à ferramenta 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 a 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 recurso de nível superior (não aninhadas) que devem ser incluídas na resposta. Por exemplo, algumas das partes de um recurso de vídeo são:
- snippet
- contentDetails
- jogador
- estatísticas
- 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. Dessa forma, o parâmetro part requer que você selecione os componentes de recursos que seu aplicativo realmente usa.Consulte Introdução à API YouTube Data para mais informações.
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 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 das playlists, 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 ver uma lista dos vídeos enviados, consulte a coluna "Envios" playlist retornada na resposta mostrada acima para informações do canal, usando o método playlistItems.list para recuperar os vídeos nessa playlist.
Antes de executar o exemplo de solicitação a seguir 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 do item de playlist. O ID do vídeo para o item da playlist é o videoId na parte contentDetails.
Você pode recuperar as listas de favoritos, marcações "Gostei", histórico de exibição ou Assistir mais tarde de um usuário usando a solicitação acima, substituindo o ID da playlist correspondente da resposta de informações do canal.
Playlists criadas por usuários
Essa solicitação usa o método playlists.list para recuperar as playlists associadas ao canal autenticado. Observe que essa solicitação não recupera as playlists geradas pelo sistema e incluídas nas informações do canal (envios, watchHistory etc.). Ela recupera apenas playlists criadas pelos usuários.
GET {base_URL}/playlists?part=snippet &mine=true
Quando você tiver o ID da playlist, é possível recuperar itens dela 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 para o 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
O recurso subscription define uma relação entre um usuário do YouTube (inscrito) e um canal. O método subscriptions.list recupera os inscritos de um determinado canal ou as inscrições de um determinado usuário, dependendo dos parâmetros incluídos na solicitação.
Inscritos no canal
Esta solicitação recupera uma lista dos inscritos no canal autenticado.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Inscrições do 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 está inscrito.
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 canal ou usuário específico realizou no YouTube, como enviar um vídeo, inscrever-se 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, às inscrições do usuário ou à página inicial personalizada do YouTube do usuário.
Atividade durante um período
Essa solicitação recupera todas as ações realizadas pelo usuário autenticado em 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 na página inicial
Esta solicitação recupera o feed de atividades personalizadas que é 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 de vídeos e canais do YouTube, use a API YouTube Analytics. A página Exemplos de solicitações de API mostra como recuperar relatórios comuns do YouTube Analytics.
Pesquisar
O método search.list permite pesquisar vídeos, canais ou playlists do YouTube que correspondem aos critérios especificados. Você pode pesquisar com base em propriedades do vídeo, palavras-chave ou tópicos (ou uma combinação desses elementos) e classificar os resultados com base em fatores como data de criação, contagem de visualizações ou classificação.
Como outras solicitações da API YouTube Data, o método search.list retorna a representação JSON de um recurso do YouTube. No entanto, ao contrário de outros recursos do YouTube, um resultado de 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 as amostras abaixo, apenas a primeira requer autenticação, pois pede especificamente "my" vídeos. Ao enviar uma solicitação não autenticada, é necessário incluir o argumento key que especifica a chave de API exclusiva para o aplicativo.
Meus vídeos mais assistidos
Esta 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 de alta definição incorporáveis
Essa solicitação procura vídeos que tenham propriedades específicas, ou seja, vídeos de alta definição que possam ser incorporados em outros sites. Os resultados são listados 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 determinado assunto
Esta solicitação executa uma pesquisa por palavras-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 temas
Uma maneira mais sofisticada de pesquisar vídeos sobre um tópico específico é usar tópicos do Freebase em vez de palavras-chave. Todos os recursos de vídeo e canal do YouTube contêm um objeto topicDetails que contém uma lista de IDs de tópicos do Freebase associados ao recurso. Uma pesquisa baseada em tópicos é mais inteligente que uma pesquisa por palavra-chave, porque um tópico do Freebase representa todos os aspectos de um conceito ou objeto do mundo real.
Para pesquisar usando um tópico do Freebase, primeiro recupere 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 de tópico é /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Pesquisar playlists ou canais
A pesquisa não se limita a vídeos. Você também pode pesquisar playlists ou canais. Esta solicitação recupera listas de reprodução 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, basta mudar o parâmetro type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Se 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 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 analisamos 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, listas de reprodução 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 Google APIs Explorer usando uma ferramenta interativa.
Crie uma assinatura
Essa 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', } }
Como adicionar um vídeo a uma lista de reprodução
Agora que 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 } }