API Reference

A API de dados do YouTube permite a incorporação de funções normalmente executadas no site do YouTube em seu próprio site ou aplicativo. A lista abaixo identifica os diferentes tipos de recursos que você pode recuperar usando a API. A API também suporta métodos para inserir, atualizar ou excluir muitos desses recursos.

Este guia de referência explica como usar a API para executar todas essas operações. O guia está organizado por tipo de recurso. Um recurso representa um tipo de item que compreende parte da experiência do YouTube, como um vídeo, uma playlist ou uma inscrição. Para cada tipo de recurso, o guia lista uma ou mais representações de dados, e os recursos são representados como objetos JSON. O guia também lista um ou mais métodos suportados (LIST, POST, DELETE etc.) para cada tipo de recurso e explica como usar esses métodos em seu aplicativo.

Chamando a API

Os seguintes requisitos aplicam-se às solicitações de API de dados do YouTube:

  1. Cada solicitação deve especificar uma chave de API (com o parâmetro key) ou fornecer um token do OAuth 2.0. Sua chave de API está disponível no painel Acesso à API do console da API para seu projeto.

  2. Você deve enviar um token de autorização para cada solicitação de inserção, atualização e exclusão. Você também deve enviar um token de autorização para qualquer solicitação que recupera os dados privados do usuário autenticado.

    Além disso, alguns métodos de API para recuperação de recursos podem suportar parâmetros que necessitam de autorização ou podem conter metadados adicionais quando as solicitações são autorizadas. Por exemplo, uma solicitação para recuperar os vídeos enviados de um usuário também pode conter vídeos privados, se a solicitação for autorizada por esse usuário específico.

  3. A API suporta o protocolo de autenticação OAuth 2.0. Você pode fornecer um token do OAuth 2.0 de uma das seguintes formas:

    • Use o parâmetro de consulta access_token como este: ?access_token=oauth2-token
    • Use o cabeçalho HTTP Authorization como este: Authorization: Bearer oauth2-token

    Instruções completas para a implementação da autenticação OAuth 2.0 em seu aplicativo podem ser encontradas no guia de autenticação.

Tipos de recursos

A API interage com os seguintes tipos de recursos:

  1. activities
  2. channelBanners
  3. channels
  4. guideCategories
  5. playlistItems
  6. playlists
  7. search
  8. subscriptions
  9. thumbnails
  10. videoCategories
  11. videos

activities

Um recurso activity contém informações sobre uma ação que um determinado canal ou usuário realizou no YouTube. As ações relatadas nos feeds de atividades incluem classificar e compartilhar um vídeo, marcar um vídeo como favorito, comentar sobre um vídeo, fazer upload de um vídeo, e assim por diante. Cada recurso activity identifica o tipo de ação, o canal associado à ação e o(s) recurso(s) associado(s) com a ação, como o vídeo que foi avaliado ou carregado.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /activities Retorna uma lista de eventos de atividade do canal que correspondem aos critérios da solicitação. Por exemplo, você pode recuperar eventos associados a um determinado canal, eventos associados a inscrições do usuário e amigos do Google+ ou o feed da página inicial do YouTube, que é personalizado para cada usuário.
insert POST /activities Mensagens de um boletim para um canal específico. (O usuário que envia a solicitação deve estar autorizado a agir em nome do canal.)

Nota: Embora um recurso de activity possa conter informações sobre ações, como classificar um vídeo de um usuário ou marcar um vídeo como favorito, você precisa usar outros métodos de API para gerar esses recursos activity. Por exemplo, você poderia usar o método videos.rate() da API para classificar um vídeo e o método playlistItems.insert() para marcar um vídeo como favorito.

channelBanners

Um recurso channelBanner contém a URL que você usaria para definir uma imagem recém-carregada como a imagem do banner de um canal.

Para mais informações sobre este recurso, consulte sua representação de recurso e a lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Carrega uma imagem de banner de canal no YouTube. Este método representa as duas primeiras etapas de um processo de três etapas para atualizar a imagem do banner para um canal:

  1. Chame o método channelBanners.insert para carregar os dados binários de imagem para o YouTube. A imagem deve ter uma proporção de 16:9 e ter pelo menos 2120 x 1192 pixels.
  2. Extraia o valor da propriedade url a partir da resposta que a API retorna para a etapa 1.
  3. Chame o método channels.update para atualizar as configurações da marca do canal. Defina o valor da propriedade brandingSettings.image.bannerExternalUrl para a URL obtida na etapa 2.

channels

Um recurso de channel contém informações sobre um canal do YouTube.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /channels Retorna um conjunto de zero ou maisl recursos de channel que correspondem aos critérios da solicitação.
update PUT /channels Atualiza os metadados de um canal. Observe que este método atualmente suporta apenas atualizações dos objetos brandingSettings e invideoPromotion do recurso channel e suas propriedades filho.

guideCategories

Um recurso de guideCategory identifica uma categoria que o YouTube atribui algoritmicamente com base no conteúdo ou em outros indicadores de um canal, como a popularidade do canal. A lista é semelhante a categorias de vídeo , com a diferença de que o aplicativo de envio de um vídeo pode atribuir uma categoria de vídeo, mas somente o YouTube pode atribuir uma categoria de canal.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /guideCategories Retorna uma lista de categorias que podem ser associadas a canais do YouTube.

playlistItems

O recurso playlistItem identifica outro recurso incluído em uma playlist, como um vídeo por exemplo. Além disso, o recurso playlistItem contém detalhes sobre o recurso incluído que dizem respeito especificamente à forma como esse recurso é usado nessa playlist.

O YouTube usa playlists para identificar conjuntos especiais de vídeos para um canal, tais como:

  • vídeos enviados
  • vídeos favoritos
  • vídeos avaliados positivamente (gostei)
  • histórico de exibição
  • assistir mais tarde
Para ser mais específico, essas listas estão associadas a um canal, que é um conjunto de vídeos de uma pessoa, grupo ou empresa, playlists e outras informações do YouTube.

Você pode recuperar o IDs da playlist para cada uma dessas listas a partir do channel resource para um determinado canal. Em seguida, você pode usar o método playlistItems.list para recuperar qualquer uma dessas listas. Você também pode adicionar ou remover itens dessas listas chamando os métodos playlistItems.insert e playlistItems.delete. Por exemplo, se um usuário marca um vídeo como um vídeo favorito, você deve inserir esse vídeo na playlist de vídeos favoritos para o canal desse usuário.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Exclui um item da playlist.
insert POST /playlistItems Adiciona um recurso a uma playlist.
list GET /playlistItems Retorna um conjunto de itens da playlist que correspondem aos parâmetros da solicitação de API. Você pode recuperar todos os itens da playlist em uma playlist especificada ou recuperar um ou mais itens da playlist por seus IDs exclusivos.
update PUT /playlistItems Modifica um item da playlist. Por exemplo, você poderia atualizar a posição do item na playlist.

playlists

Um recurso de playlist representa uma lista de reprodução do YouTube. Uma playlist é um conjunto de vídeos que podem ser visualizados em sequência e compartilhados com outros usuários. Uma playlist pode conter até 200 vídeos e o YouTube não limita o número de playlists que cada usuário cria. Por padrão, as playlists ficam visíveis publicamente a outros usuários, mas elas podem ser públicas ou privadas.

O YouTube também usa playlists para identificar conjuntos especiais de vídeos para um canal, tais como:

  • vídeos enviados
  • vídeos favoritos
  • vídeos avaliados positivamente (gostei)
  • histórico de exibição
  • assistir mais tarde
Para ser mais específico, essas listas estão associadas a um canal, que é um conjunto de vídeos de uma pessoa, grupo ou empresa, playlists, e outras informações do YouTube. Você pode recuperar o IDs das playlists para cada uma dessas listas do channel resource para um determinado canal.

Em seguida, você pode usar o método playlistItems.list para recuperar qualquer uma dessas listas. Você também pode adicionar ou remover itens dessas listas chamando os métodos playlistItems.insert e playlistItems.delete.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /playlists Exclui uma playlist.
list GET /playlists Retorna um conjunto de playlists que correspondem aos parâmetros da solicitação de API. Por exemplo, você pode recuperar todas as playlists que o usuário autenticado possui ou recuperar uma ou mais playlists por seus IDs únicos.
insert POST /playlists Cria uma playlist.
update PUT /playlists Modifica uma playlist. Por exemplo, você pode alterar o título, a descrição ou o status de privacidade de uma playlist.

Um resultado de pesquisa contém informações sobre um vídeo, canal ou playlist do YouTube que correspondem a parâmetros de pesquisa especificados em uma solicitação de API. Embora um resultado de pesquisa aponte para um recurso exclusivamente identificável, como um vídeo, ele não tem seus próprios dados persistentes.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /search Retorna um conjunto de resultados de pesquisa que correspondem a parâmetros de consulta especificados na solicitação da API. Por padrão, um conjunto de resultados de pesquisa identifica recursos de video, channel e playlist correspondentes, mas você também pode configurar consultas para recuperar somente um tipo específico de recurso.

subscriptions

Um recurso de subscription contém informações sobre uma inscrição de usuário do YouTube. Uma inscrição notifica o usuário quando novos vídeos são adicionados a um canal ou quando outro usuário executa uma das várias ações no YouTube, como o upload ou a classificação de um vídeo ou comentários sobre um vídeo.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Exclui uma inscrição.
insert POST /subscriptions Adiciona uma inscrição para o canal do usuário autenticado.
list GET /subscriptions Retorna recursos de inscrição que correspondem a critérios da solicitação da API.

thumbnails

Um recurso thumbnail identifica diferentes tamanhos de imagens em miniatura associadas a um recurso. Observe as seguintes características das imagens em miniatura:

  • Uma propriedade snippet.thumbnails do recurso é um objeto que identifica as imagens em miniatura disponíveis para esse recurso.
  • Um recurso thumbnail contém uma série de objetos. O nome de cada objeto (default, medium, high, etc.) refere-se ao tamanho da imagem em miniatura.
  • Diferentes tipos de recursos podem suportar diferentes tamanhos de imagens em miniatura.
  • Diferentes tipos de recursos podem definir tamanhos diferentes para imagens em miniatura com o mesmo nome. Por exemplo, a imagem em miniatura default de um recurso de video normalmente é 120px por 90px, e a imagem em miniatura default para um recurso de channel normalmente é 88px por 88px.
  • Recursos do mesmo tipo ainda podem ter diferentes tamanhos de imagem em miniatura para determinadas imagens, dependendo da resolução da imagem original ou do conteúdo carregado no YouTube. Por exemplo, um vídeo em HD pode apoiar miniaturas de resolução maior que vídeos não-HD.
  • Cada objeto que contém informações sobre um tamanho de imagem em miniatura tem uma propriedade width e uma propriedade height. No entanto, as propriedades de largura e altura podem não ser retornadas para essa imagem.
  • Se uma imagem em miniatura carregada não corresponder às dimensões necessárias, a imagem será redimensionada para corresponder ao tamanho correto, sem alteração de sua proporção. A imagem não é cortada, mas pode incluir barras pretas para que o tamanho fique correto.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Carrega uma miniatura de vídeo personalizada para o YouTube e a define para um vídeo.

videoCategories

Um recurso videoCategory identifica uma categoria que foi associada ou poderia ser associada a vídeos enviados.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
list GET /videoCategories Retorna uma lista de categorias que podem ser associadas a vídeos do YouTube.

videos

Um recurso de video representa um vídeo do YouTube.

Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.

Método Solicitação HTTP Descrição
URIs relacionados a https://www.googleapis.com/youtube/v3
insert POST /videos Envia um vídeo para o YouTube e, opcionalmente, define os metadados do vídeo.
list GET /videos Retorna uma lista de vídeos que correspondem aos parâmetros de solicitação da API.
delete DELETE /videos Exclui um vídeo do YouTube.
update PUT /videos Atualiza os metadados de um vídeocanal..
rate POST /videos/rate Adiciona uma classificação gostei ou não gostei a um vídeo ou remove uma classificação de um vídeo.
getRating GET /videos/getRating Recupera as classificações que o usuário autorizado deu a uma lista de vídeos especificados.