API Reference

L'API YouTube Data vous permet d'intégrer des fonctions normalement exécutées sur le site Web YouTube à votre propre site Web ou application. Les listes ci-dessous identifient les différents types de ressources que vous pouvez récupérer à l'aide de l'API. L'API est également compatible avec 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 sous la forme d'objets JSON. Le guide répertorie é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 demandes 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 API de la Developer Console pour votre projet.

2. Vous devez envoyer un jeton d'autorisation pour chaque demande 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 accepter les paramètres nécessitant une autorisation ou contenir 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 la demande est autorisée par cet utilisateur spécifique.

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

   Pour obtenir des instructions complètes sur la mise en œuvre de l'authentification OAuth 2.0 dans votre application, consultez le guide sur l'authentification.

Types de ressources

Activités

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

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

Méthode	Requête HTTP :	Description
URI relatifs à https://www.googleapis.com/youtube/v3
list	GET /activities	Affiche la liste des événements d'activité de la 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 spécifique ou à sa propre chaîne.
insert	POST /activities	Remarque : Cette méthode a été abandonnée 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 sa représentation des ressources et la liste des 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 la liste des pistes de sous-titres associées à une vidéo donné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 mettez à jour une piste de sous-titres, vous pouvez modifier son état de brouillon et/ou importer un nouveau fichier de sous-titres pour la piste.

Bannières de chaîne

Une ressource channelBanner contient l'URL que vous utiliseriez pour définir une nouvelle image importée comme image de bannière pour une chaîne.

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

Méthode	Requête HTTP :	Description
URI relatifs à https://www.googleapis.com/youtube/v3
insert	POST /channelBanners/insert	met en ligne une bannière de chaîne sur YouTube ; Cette méthode représente les deux premières étapes d'un processus en trois étapes visant à mettre à jour l'image de bannière d'une chaîne: 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 faire au moins 2 048 x 1 152 pixels. Nous vous recommandons d'importer une image de 2 560 x 1 440 pixels. Extrayez la valeur de la propriété url de la réponse que l'API renvoie à l'étape 1. 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.

Sections de chaîne

Une ressource channelSection contient des informations sur un ensemble de vidéos choisi par une chaîne. 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 elles s'affichent dans l'affichage "Parcourir" (et non dans un flux). Pour permettre à une chaîne d'afficher du contenu dans une vue de navigation, définissez la propriété brandingSettings.channel.showBrowseView sur true pour la chaîne spécifiée.

Une chaîne peut créer 10 étagères au maximum.

Pour en savoir plus sur cette ressource, consultez sa représentation des ressources et la liste des 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é. Une chaîne peut créer jusqu'à 10 étagères.
list	GET /channelSections	Renvoie une liste de ressources channelSection correspondant aux critères de requête de l'API.
update	PUT /channelSections	Met à jour une section de chaîne.

Chaînes

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

Pour en savoir plus sur cette ressource, consultez sa représentation des ressources et la liste des 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 ou plusieurs ressources channel correspondant aux critères de requête.
update	PUT /channels	Met à jour les métadonnées d'une chaîne. Notez que cette méthode n'accepte actuellement que les mises à jour des objets brandingSettings et invideoPromotion de la ressource channel et de leurs propriétés enfants.

Fils de discussion

Une ressource commentThread contient des informations sur un fil de commentaires YouTube, qui comprennent un commentaire de premier niveau et les réponses à ce commentaire, le cas échéant. 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 fait 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 sa représentation des ressources et la liste des 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 qui correspondent 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 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 sa représentation des ressources et la liste des 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 demande d'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	exprime l'avis de l'appelant qu'un ou plusieurs commentaires doivent être signalés comme spam.
delete	DELETE /comments	Supprime un commentaire.
update	PUT /comments	Modifie un commentaire.

GuideCatégories

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

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

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

Langues

Une ressource i18nLanguage identifie une langue d'application acceptée par le site Web YouTube. La langue de l'application peut également être désignée comme langue de l'interface utilisateur. Sur le site Web YouTube, vous pouvez sélectionner automatiquement la langue de l'application en fonction des paramètres de votre compte Google, de la langue du navigateur ou de l'adresse IP. L'utilisateur peut également sélectionner manuellement la langue souhaitée 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 sa représentation des ressources et la liste des 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 acceptées par le site Web YouTube.

Régions

Une ressource i18nRegion identifie une zone géographique qu'un utilisateur YouTube peut sélectionner comme région de contenu préférée. La région de contenu est également appelée "paramètres régionaux du contenu". Pour le site YouTube, une région de contenu peut être sélectionnée automatiquement en fonction de critères heuristiques tels que le domaine YouTube ou l'adresse IP de l'utilisateur. L'utilisateur peut également sélectionner manuellement la région de contenu souhaitée dans le pied de page du site YouTube.

Chaque ressource i18nRegion identifie un code de région 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 sa représentation des ressources et la liste des 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 un membre d'une chaîne YouTube. Un membre fournit un soutien financier récurrent à un créateur et bénéficie d'avantages spéciaux. Par exemple, les membres peuvent discuter lorsque le créateur active le mode réservé aux membres.

Pour en savoir plus sur cette ressource, consultez sa 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 "sponsors") d'une chaîne. La demande d'API doit être autorisée par le propriétaire de la chaîne.

Niveaux de souscription

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

Éléments de la playlist

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 l'utilisation de cette ressource dans cette playlist.

YouTube utilise également une playlist pour identifier la liste des vidéos mises en ligne sur une chaîne, chaque playlistItem représentant une vidéo mise en ligne. Vous pouvez récupérer l'ID de la playlist de cette liste à partir de channel resource pour une chaîne donnée. Vous pouvez ensuite utiliser la méthode playlistItems.list pour ajouter à la liste.

Pour en savoir plus sur cette ressource, consultez sa représentation des ressources et la liste des 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 playlist.
insert	POST /playlistItems	Ajoute une ressource à une playlist.
list	GET /playlistItems	Renvoie un ensemble d'éléments de playlist qui correspondent aux paramètres de requête de l'API. Vous pouvez récupérer tous les éléments d'une playlist donnée ou en extraire un ou plusieurs par ID.
update	PUT /playlistItems	Modifie un élément de playlist. Par exemple, vous pouvez 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 de manière séquentielle et partagées avec d'autres utilisateurs. Une playlist peut contenir jusqu'à 200 vidéos, et le nombre de playlists créées par chaque utilisateur sur YouTube n'est pas limité. Par défaut, les autres utilisateurs peuvent voir les playlists, mais elles peuvent être publiques ou privées.

YouTube utilise également des playlists pour identifier des ensembles de vidéos spécifiques sur une chaîne, par exemple:

• vidéos mises en ligne
• vidéos évalués de façon positive (J'aime)
• historique des vidéos regardées
• regarder plus tard

Vous pouvez récupérer les ID de playlist de chacune de ces listes à partir de channel resource pour 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 articles de ces listes en appelant les méthodes playlistItems.insert et playlistItems.delete.

Pour en savoir plus sur cette ressource, consultez sa représentation des ressources et la liste des 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 un ensemble de playlists qui correspondent aux paramètres de requête de l'API. Par exemple, vous pouvez récupérer toutes les playlists dont l'utilisateur authentifié est propriétaire, ou une ou plusieurs playlists par 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 le niveau de confidentialité d'une playlist.

Rechercher

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 façon unique, comme une vidéo, il ne possède pas ses propres données persistantes.

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

Méthode	Requête HTTP :	Description
URI relatifs à https://www.googleapis.com/youtube/v3
list	GET /search	Renvoie un ensemble 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 les requêtes pour ne récupérer qu'un type de ressource spécifique.

Abonnements

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

Pour en savoir plus sur cette ressource, consultez sa représentation des ressources et la liste des 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	Renvoie les ressources d'abonnement correspondant aux critères de requête de l'API.

Miniatures

Une ressource thumbnail identifie les différentes tailles d'images miniatures 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.) fait référence à la taille de la vignette.
• Différents types de ressources peuvent accepter différentes tailles d'images miniatures.
• Différents types de ressources peuvent définir différentes tailles pour les vignettes portant le même nom. Par exemple, l'image miniature default d'une ressource video mesure généralement 120 x 90 pixels, tandis que l'image miniature default d'une ressource channel mesure généralement 88 x 88 pixels.
• Selon la résolution de l'image d'origine ou du contenu mis en ligne sur YouTube, les ressources du même type peuvent toujours avoir des tailles différentes pour certaines images. Par exemple, une vidéo HD peut être compatible avec des miniatures de résolution supérieure à celle des vidéos non HD.
• Chaque objet contenant des informations sur la taille de l'image miniature possède une propriété width et une propriété height. Toutefois, il est possible que les propriétés de largeur et de hauteur ne soient pas renvoyées pour cette image.
• Si les dimensions d'une vignette importée ne correspondent pas aux dimensions requises, l'image est redimensionnée afin de correspondre à la taille correcte sans modifier ses proportions. L'image n'est pas recadrée, mais peut inclure des barres noires pour que la taille soit correcte.

Pour en savoir plus sur cette ressource, consultez sa représentation des ressources et la liste des 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 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 pour son 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 la raison pour laquelle la vidéo est signalée.

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

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

Catégories de vidéos

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 sa représentation des ressources et la liste des propriétés.

Méthode	Requête HTTP :	Description
URI relatifs à https://www.googleapis.com/youtube/v3
list	GET /videoCategories	Affiche la liste des 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 sa représentation des ressources et la liste des propriétés.

Méthode	Requête HTTP :	Description
URI relatifs à https://www.googleapis.com/youtube/v3
insert	POST /videos	Mettre en ligne une vidéo sur YouTube et définir éventuellement ses métadonnées
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	Ajouter une note "J'aime" ou "Je n'aime pas" à une vidéo, ou supprimer une note d'une vidéo
getRating	GET /videos/getRating	Récupère les notes attribuées par l'utilisateur autorisé à une liste de vidéos spécifiées.
reportAbuse	POST /videos/reportAbuse	Signaler une vidéo dont le contenu est abusif.

Filigranes

Une ressource watermark identifie une image qui s'affiche pendant la lecture des vidéos d'une chaîne spécifique. Vous pouvez également spécifier une chaîne cible vers laquelle l'image redirigera, ainsi que des codes temporels qui déterminent quand le filigrane s'affiche pendant la lecture des vidéos et leur durée d'affichage.

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

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