API Reference

L'API YouTube Data vous permet d'incorporer dans votre site Web ou dans votre application des fonctions normalement exécutées sur le site Web YouTube. Les listes ci-dessous identifient les différents types de ressources que vous pouvez récupérer à l'aide de l'API. L'API prend également en charge des méthodes permettant d'insérer, de mettre à jour ou de supprimer un grand nombre de ces ressources.

Ce guide de référence explique comment utiliser l'API pour effectuer toutes ces opérations. Le guide est organisé par type de ressource. Une ressource représente un type d'élément qui fait partie de l'expérience YouTube, comme une vidéo, une playlist ou un abonnement. Pour chaque type de ressource, le guide répertorie une ou plusieurs représentations de données, et les ressources sont représentées par des objets JSON. Il liste également une ou plusieurs méthodes compatibles (LIST, POST, DELETE, etc.) pour chaque type de ressource, et explique comment les utiliser dans votre application.

Appeler l'API

Les exigences suivantes s'appliquent aux requêtes de l'API YouTube Data:

  1. Chaque requête doit spécifier une clé API (avec le paramètre key) ou fournir un jeton OAuth 2.0. Votre clé API est disponible dans le volet Accès à l'API de la Developer Console pour votre projet.

  2. Vous devez envoyer un jeton d'autorisation pour chaque requête d'insertion, de mise à jour et de suppression. Vous devez également envoyer un jeton d'autorisation pour toute requête qui récupère les données privées de l'utilisateur authentifié.

    En outre, certaines méthodes d'API permettant de récupérer des ressources peuvent être compatibles avec des paramètres nécessitant une autorisation ou contenant des métadonnées supplémentaires lorsque les requêtes sont autorisées. Par exemple, une demande de récupération des vidéos mises en ligne par un utilisateur peut également contenir des vidéos privées si elle est autorisée par cet utilisateur.

  3. L'API est compatible avec le protocole d'authentification OAuth 2.0. Vous pouvez fournir un jeton OAuth 2.0 de l'une des manières suivantes:

    • Utilisez le paramètre de requête access_token comme suit: ?access_token=oauth2-token
    • Utilisez l'en-tête HTTP Authorization comme suit: Authorization: Bearer oauth2-token

    Consultez le guide d'authentification pour découvrir en détail comment implémenter l'authentification OAuth 2.0 dans votre application.

Types de ressources

Activités

Une ressource activity contient des informations sur une action effectuée par une chaîne ou un utilisateur sur YouTube. Les actions enregistrées dans les flux d'activités comprennent l'évaluation d'une vidéo, le partage d'une vidéo, l'ajout d'une vidéo aux favoris, la mise en ligne d'une vidéo, etc. Chaque ressource activity identifie le type d'action, la chaîne associée à l'action et la ou les ressources associées à l'action, comme la vidéo qui a été évaluée ou mise en ligne.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /activities Renvoie la liste des événements d'activité de chaîne qui correspondent aux critères de la requête. Par exemple, vous pouvez récupérer les événements associés à un canal particulier ou au canal de l'utilisateur.
insert POST /activities Remarque:Cette méthode est obsolète et n'est plus acceptée.

Sous-titres

Une ressource caption représente une piste de sous-titres YouTube. Une piste de sous-titres est associée à une seule vidéo YouTube.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
delete DELETE /captions Supprime la piste de sous-titres spécifiée.
download GET /captions/id Télécharge une piste de sous-titres. La piste de sous-titres est renvoyée dans son format d'origine, sauf si la requête spécifie une valeur pour le paramètre tfmt et dans sa langue d'origine, sauf si elle spécifie une valeur pour le paramètre tlang.
insert POST /captions Importe une piste de sous-titres.
list GET /captions Renvoie une liste de pistes de sous-titres associées à une vidéo spécifiée. Notez que la réponse de l'API ne contient pas les sous-titres réels et que la méthode captions.download permet de récupérer une piste de sous-titres.
update PUT /captions Met à jour une piste de sous-titres. Lorsque vous modifiez une piste de sous-titres, vous pouvez modifier son état brouillon et/ou importer un nouveau fichier de sous-titres pour cette piste.

ChannelBanners

Une ressource channelBanner contient l'URL que vous devez utiliser pour définir une nouvelle image en tant qu'image de bannière de votre chaîne.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Il met en ligne sur YouTube une image de bannière de chaîne. Cette méthode représente les deux premières étapes d'un processus en trois étapes visant à mettre à jour l'image de la bannière d'une chaîne:

  1. Appelez la méthode channelBanners.insert pour importer les données de l'image binaire sur YouTube. L'image doit être au format 16:9 et mesurer au moins 2 048 x 1 152 pixels. Nous vous recommandons d'importer une image de 2 560 x 1 440 pixels.
  2. Extrayez la valeur de la propriété url de la réponse renvoyée par l'API à l'étape 1.
  3. Appelez la méthode channels.update pour mettre à jour les paramètres de branding de la chaîne. Définissez la valeur de la propriété brandingSettings.image.bannerExternalUrl sur l'URL obtenue à l'étape 2.

ChannelSections

Une ressource channelSection contient des informations sur un ensemble de vidéos qu'une chaîne a choisi de présenter. Par exemple, une section peut présenter les dernières vidéos mises en ligne, les vidéos les plus populaires ou les vidéos d'une ou plusieurs playlists.

Sachez que les sections d'une chaîne ne sont visibles que si le contenu de la chaîne s'affiche dans un affichage "Parcourir" (et non dans un flux). Pour permettre à une chaîne d'afficher du contenu dans une vue "Parcourir", définissez la propriété brandingSettings.channel.showBrowseView sur true pour la chaîne spécifiée.

Une chaîne peut créer jusqu'à 10 sections.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Supprime une section de chaîne.
insert POST /channelSections Ajoute une section de canal à la chaîne de l'utilisateur authentifié. Vous pouvez créer jusqu'à 10 sections par chaîne.
list GET /channelSections Renvoie une liste de ressources channelSection correspondant aux critères de requête API.
update PUT /channelSections Met à jour une section de chaîne.

Canaux

Une ressource channel contient des informations sur une chaîne YouTube.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /channels Renvoie une collection de zéro, une ou plusieurs ressources channel correspondant aux critères de la requête.
update PUT /channels Met à jour les métadonnées d'une chaîne. Notez que cette méthode n'est actuellement compatible qu'avec les mises à jour des objets brandingSettings et invideoPromotion de la ressource channel, ainsi que de leurs propriétés enfants.

CommentThreads

Une ressource commentThread contient des informations sur un fil de commentaires YouTube, qui comprend un commentaire de premier niveau et, le cas échéant, des réponses à ce commentaire. Une ressource commentThread peut représenter des commentaires sur une vidéo ou une chaîne.

Le commentaire de premier niveau et les réponses sont en réalité des ressources comment imbriquées dans la ressource commentThread. La ressource commentThread ne contient pas nécessairement toutes les réponses à un commentaire. Vous devez utiliser la méthode comments.list si vous souhaitez récupérer toutes les réponses à un commentaire particulier. Notez également que certains commentaires n'ont pas de réponse.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /commentThreads Renvoie une liste de fils de commentaires correspondant aux paramètres de requête de l'API.
insert POST /commentThreads Crée un commentaire de premier niveau. Pour ajouter une réponse à un commentaire existant, utilisez plutôt la méthode comments.insert.

Commentaires

Une ressource comment contient des informations sur un seul commentaire YouTube. Une ressource comment peut représenter un commentaire sur une vidéo ou une chaîne. Il peut également s'agir d'un commentaire de premier niveau ou d'une réponse à un commentaire de premier niveau.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /comments Renvoie une liste de commentaires correspondant aux paramètres de requête de l'API.
setModerationStatus POST /comments/setModerationStatus Définit l'état de modération d'un ou de plusieurs commentaires. La requête API doit être autorisée par le propriétaire de la chaîne ou de la vidéo associée aux commentaires.
insert POST /comments Crée une réponse à un commentaire existant. Remarque:Pour créer un commentaire de premier niveau, utilisez la méthode commentThreads.insert.
markAsSpam POST /comments/markAsSpam Remarque:Cette méthode est obsolète et n'est plus acceptée.
delete DELETE /comments Supprime un commentaire.
update PUT /comments Modifie un commentaire.

GuideCategories

Une ressource guideCategory identifie une catégorie attribuée par un algorithme de YouTube en fonction du contenu d'une chaîne ou d'autres indicateurs tels que sa popularité. La liste est semblable aux catégories de vidéos, à la différence que l'utilisateur qui a mis en ligne une vidéo peut attribuer une catégorie de vidéo, mais que seul YouTube peut attribuer une catégorie de chaîne.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /guideCategories Affiche une liste de catégories pouvant être associées à des chaînes YouTube.

I18nLanguages

Une ressource i18nLanguage identifie la langue de l'application disponible sur le site Web YouTube. Le langage de l'application peut également être désigné par le terme "langage d'interface utilisateur". Pour le site Web YouTube, une langue d'application peut être sélectionnée automatiquement en fonction des paramètres du compte Google, de la langue du navigateur ou de l'adresse IP. L'utilisateur peut également sélectionner manuellement la langue de l'interface utilisateur dans le pied de page du site YouTube.

Chaque ressource i18nLanguage identifie un code de langue et un nom. Le code de langue peut être utilisé comme valeur du paramètre hl lorsque vous appelez des méthodes d'API telles que videoCategories.list et guideCategories.list.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Affiche la liste des langues prises en charge par le site YouTube.

I18nRegions

Une ressource i18nRegion identifie la zone géographique qu'un utilisateur YouTube peut sélectionner comme région de contenu préférée. La région du contenu peut également être désignée par l'expression "Paramètres régionaux du contenu". Pour le site Web YouTube, une région de contenu peut être automatiquement sélectionnée en fonction d'heuristiques comme le domaine YouTube ou l'adresse IP de l'utilisateur. L'utilisateur peut également sélectionner manuellement la région de son choix dans le pied de page du site YouTube.

Chaque ressource i18nRegion identifie un code régional et un nom. Le code de région peut être utilisé comme valeur du paramètre regionCode lorsque vous appelez des méthodes d'API telles que search.list, videos.list, activities.list et videoCategories.list.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /i18nRegions Affiche la liste des régions de contenu acceptées par le site Web YouTube.

Membres

Une ressource member représente le membre d'une chaîne YouTube. Un membre offre un soutien financier récurrent à un créateur et reçoit des avantages spéciaux. Par exemple, les membres peuvent discuter lorsque le créateur active le mode réservé aux membres pour un chat.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /members Liste les membres (anciennement appelés "sponsors") d'une chaîne. La requête API doit être autorisée par le propriétaire de la chaîne.

MembershipsLevels

Une ressource membershipsLevel identifie un niveau de tarification pour le créateur qui a autorisé la requête API.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Renvoie une collection de zéro, une ou plusieurs ressources membershipsLevel appartenant au canal qui a autorisé la requête API. Les niveaux sont renvoyés dans un ordre d'affichage implicite.

PlaylistItems

Une ressource playlistItem identifie une autre ressource, telle qu'une vidéo, qui est incluse dans une playlist. En outre, la ressource playlistItem contient des informations sur la ressource incluse qui concernent spécifiquement son utilisation dans la playlist.

YouTube utilise également une playlist pour identifier la liste des vidéos mises en ligne d'une chaîne. Chaque playlistItem de cette liste représente une vidéo mise en ligne. Vous pouvez récupérer l'ID de cette liste dans le fichier channel resource d'une chaîne donnée. Vous pouvez ensuite utiliser la méthode playlistItems.list pour la liste.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Supprime un élément de la playlist.
insert POST /playlistItems Ajoute une ressource à une playlist.
list GET /playlistItems Renvoie une collection d'éléments de playlist correspondant aux paramètres de requête de l'API. Vous pouvez récupérer tous les éléments d'une playlist spécifique, ou un ou plusieurs éléments d'une playlist en fonction de leur ID unique.
update PUT /playlistItems Modifie un élément de la playlist. Vous pouvez, par exemple, modifier la position de l'élément dans la playlist.

Playlists

Une ressource playlist représente une playlist YouTube. Une playlist est un ensemble de vidéos qui peuvent être regardées successivement et partagées avec d'autres utilisateurs. Une playlist peut contenir jusqu'à 200 vidéos, et YouTube ne limite pas le nombre de playlists créées par chaque utilisateur. Par défaut, les playlists sont visibles par tous les utilisateurs, mais elles peuvent être publiques ou privées.

YouTube utilise également les playlists pour identifier des collections spéciales de vidéos pour une chaîne. Par exemple:

  • vidéos mises en ligne
  • vidéos ayant reçu une note positive
  • historique des vidéos regardées
  • regarder plus tard
Plus précisément, ces listes sont associées à une chaîne, qui comprend les vidéos, les playlists et d'autres informations YouTube d'une personne, d'un groupe ou d'une entreprise. Vous pouvez récupérer les ID des playlists de chacune de ces listes à partir du fichier channel resource d'une chaîne donnée.

Vous pouvez ensuite utiliser la méthode playlistItems.list pour récupérer l'une de ces listes. Vous pouvez également ajouter ou supprimer des éléments de ces listes en appelant les méthodes playlistItems.insert et playlistItems.delete.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
delete DELETE /playlists Supprime une playlist.
list GET /playlists Renvoie une collection de playlists qui correspondent aux paramètres de requête de l'API. Par exemple, vous pouvez récupérer toutes les playlists appartenant à l'utilisateur authentifié, ou une ou plusieurs playlists en fonction de leur ID unique.
insert POST /playlists Crée une playlist.
update PUT /playlists Modifie une playlist. Par exemple, vous pouvez modifier le titre, la description ou l'état de confidentialité d'une playlist.

Un résultat de recherche contient des informations sur une vidéo, une chaîne ou une playlist YouTube qui correspondent aux paramètres de recherche spécifiés dans une requête API. Bien qu'un résultat de recherche pointe vers une ressource identifiable de manière unique, telle qu'une vidéo, il ne possède pas ses propres données persistantes.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /search Affiche une collection de résultats de recherche correspondant aux paramètres de requête spécifiés dans la requête API. Par défaut, un ensemble de résultats de recherche identifie les ressources video, channel et playlist correspondantes, mais vous pouvez également configurer des requêtes pour ne récupérer qu'un type de ressource spécifique.

Abonnements

Une ressource subscription contient des informations sur l'abonnement d'un utilisateur YouTube. Un abonnement avertit un utilisateur lorsque de nouvelles vidéos sont ajoutées à une chaîne ou lorsqu'un autre utilisateur effectue l'une des actions possibles sur YouTube, comme mettre en ligne une vidéo, donner son avis sur une vidéo ou laisser un commentaire.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Supprime un abonnement.
insert POST /subscriptions Ajoute un abonnement à la chaîne de l'utilisateur authentifié.
list GET /subscriptions Affiche les ressources d'abonnement qui correspondent aux critères de requête API.

Miniatures

Une ressource thumbnail identifie différentes tailles d'image de vignette associées à une ressource. Veuillez noter les caractéristiques suivantes des vignettes:

  • La propriété snippet.thumbnails d'une ressource est un objet qui identifie les vignettes disponibles pour cette ressource.
  • Une ressource thumbnail contient une série d'objets. Le nom de chaque objet (default, medium, high, etc.) correspond à la taille de l'image miniature.
  • Chaque type de ressource accepte différentes tailles de vignettes.
  • Différents types de ressources peuvent définir différentes tailles pour les vignettes portant le même nom. Par exemple, la vignette default d'une ressource video mesure généralement 120 x 90 pixels, tandis que la vignette default d'une ressource channel mesure 88 x 88 pixels.
  • Des ressources du même type peuvent toujours avoir des tailles de miniature différentes pour certaines images, en fonction de la résolution de l'image d'origine ou du contenu mis en ligne sur YouTube. Par exemple, une vidéo HD peut être compatible avec des miniatures de meilleure résolution que les vidéos non HD.
  • Chaque objet qui contient des informations sur la taille d'une vignette possède une propriété width et une propriété height. Toutefois, les propriétés de largeur et de hauteur ne peuvent pas être renvoyées pour cette image.
  • Si une vignette importée ne correspond pas aux dimensions requises, elle est redimensionnée pour correspondre à la taille correcte sans modifier ses proportions. L'image n'est pas recadrée, mais des barres noires peuvent apparaître afin que la taille soit correcte.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Met en ligne une miniature de vidéo personnalisée sur YouTube et la définit pour une vidéo.

VideoAbuseReportReasons

Une ressource videoAbuseReportReason contient des informations sur les raisons pour lesquelles une vidéo peut être signalée comme présentant du contenu abusif. Lorsque votre application appelle la méthode videos.reportAbuse pour signaler une vidéo abusive, la requête utilise les informations d'une ressource videoAbuseReportReason pour identifier le motif du signalement.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Obtenez la liste des motifs pouvant être utilisés pour signaler des vidéos abusives.

VideoCategories

Une ressource videoCategory identifie une catégorie qui a été ou pourrait être associée à des vidéos mises en ligne.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
list GET /videoCategories Affiche une liste de catégories pouvant être associées à des vidéos YouTube.

Vidéos

Une ressource video représente une vidéo YouTube.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
insert POST /videos Met en ligne une vidéo sur YouTube et définit éventuellement les métadonnées de la vidéo.
list GET /videos Renvoie une liste de vidéos qui correspondent aux paramètres de requête de l'API.
delete DELETE /videos Supprime une vidéo YouTube.
update PUT /videos Met à jour les métadonnées d'une vidéo.
rate POST /videos/rate Attribuer une mention "J'aime" ou "Je n'aime pas" à une vidéo, ou supprimer une note sur une vidéo
getRating GET /videos/getRating Récupère les classifications que l'utilisateur autorisé a attribuées à une liste de vidéos spécifiées.
reportAbuse POST /videos/reportAbuse Signaler une vidéo présentant du contenu abusif

Filigranes

Une ressource watermark identifie une image qui s'affiche lors de la lecture des vidéos d'une chaîne spécifiée. Vous pouvez également spécifier un canal cible vers lequel l'image sera associée, ainsi que des informations temporelles qui déterminent le moment où le filigrane apparaît lors de la lecture de la vidéo et sa durée de visibilité.

Pour en savoir plus sur cette ressource, consultez la section concernant la représentation des ressources et la liste de ses propriétés.

Méthode Requête HTTP Description
URI relatifs à https://www.googleapis.com/youtube/v3
set POST /watermarks/set Il met en ligne une image en filigrane sur YouTube et l'associe à une chaîne.
unset POST /watermarks/unset Supprime le filigrane d'une chaîne.