Détails: Catégorie : Les API du web

View Comments

La gestion des recherches sur Youtube Après une petite pause effectuée pour diverses raisons, continuons notre exploration des API de youtube. Aujourd'hui, nous allons lancer des recherches au coeur meme de Youtube, et nous allons traiter/récupérer les résultats retournés par le site Youtube.
Le principe est comme d'habitude simple ;: nous lançons une requette http au travers via le lancement d'un URL et nous récupérons les résultats, ceux-ci étant retournés aux format JSON.
Gardez en tete que, meme si les recherches peuvent retourner l'ensemble des résultats trouvés dans youtube, ceux-ci sont plutot classés par pertinence de date : les derniers ajouts seront souvent les premiers résultats retournés.
Pour lancer une recherche, nous avons, comme avec Google, besoin d'une chaine de caractères représentant ce que vous souhaitez rechercher. Dans les exemples que nous allons développer ici, nous allons faire une recherche avec le terme "COVID" (c'est d'actualité).

Recherches avec 1 seul mot

Ce cas de figure est le plus simple. L'utilisateur souhaite faire une recherche sur un mot clef. Un seul mot clef. Dans ce cas, il "suffit" de passer le mot clef recherché dans l'URL de la manière suivante :

https://www.googleapis.com/youtube/v3/search?part=snippet&q=aimant&key=[VOTRE_CLEF_API]

Toutefois, afin de ne pas etre confronté à un nombre phénoménal de résultats, il est possible de limiter le nombre de résultats retournés en rajoutant dans l'URL le nombre maximum de résultats. Si ce paramètre est omis, le nombre de résultats retournés est au nombre de 10.

https://www.googleapis.com/youtube/v3/search?part=snippet&q=aimant&key=[VOTRE_CLEF_API]

Avec 2 ou n mots

Bien entendu, vous pouvez lancer une recherche sur Youtube via les API afin de lisiter les videos. Cette fonctionnalité peut etre interessante pour "trouver" de nouvelles vidéos ajoutée à la plateforme Youtube.
Pour lancer une recherche sur plusieurs termes, deux options sont possibles entre les termes : soit on utilise l'espace (qui, encodé URL devient %20), soit on utilise le symbole +. Ainsi, si l'on veut trouver les vidéos d'explosions du youtubeur ExperimentBoy, l'URL à lancer devient https://www.googleapis.com/youtube/v3/search?part=snippet&q=explosions+experimentboy&key=[VOTRE_CLEF_API].

Limiter le nombre de resultats retournés

Nous ne l'avons pas encore vu car une valeur par défaut est fixée dans l'API de Youtube, mais il est possible de limiter (ou maximiser) le nombre de résultats retournés par la recherche lancée via l'API.
Pour limiter le nombre de résultats renvoyés, Youtube propose, dans l'utilisation de son API, la possibilité de rajouter un paramètre dans lequel il est possible de stipuler le nombre maximal de résultats. Ce paramètre est maxResults. Ainsi, pour afficher 5 résultats sur le terme "Nancy", la requete ressemblera à https://www.googleapis.com/youtube/v3/search?part=snippet&maxResults=5&q=nancy&key=[VOTRE_CLEF_API]

Limiter les recherches aux videos uniquement en Francais

La limitation sur la langue est aussi possible. De ce fait, il est possible d'effectuer une recherche sur un mot-clef qui a une meme orthographe (mais un sens différent) selon la langue utilisée. Prenons le mot "pain" : en francais, il représente laccompagnement d'un repas, alors qu'en anglais, il représente la douleur. Pour ne rechercher que des videos sur le pain (que l'on mange) et bannir les vidéos des Maitresses anglophones sado-masochistes (encore qu'il n'y en a peu mais il peut y avoir des videos de donjons par exemple), nous allons spécifier la langue dans laquelle la rechercher va etre effectuée de la manière suivante : &relevanceLanguage=fr
https://www.googleapis.com/youtube/v3/search?part=snippet&maxResults=5&q=pain&relevanceLanguage=fr&key=[VOTRE_CLEF_API]
La chaine fr correspond à la langue. La liste des chaines officielles représentant les langues sont régies par la norme ISO 639.

Pour des recherches dans un canal spécifié

Il est aussi possible de faire une recherche sur une chaine Youtube spécifiée. Cette fonctionnalité peut etre très intéressante pour monter sur votre site web un petit moteur de recherche de votre chaine Youtube.
Pour lancer une recherche sur votre chaine (ou canal, c'est vraiment la meme chose), il faut utiliser la commande https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=[REFERENCE DE VOTRE CANAL]&maxResults=50&q=[TERME RECHERCHE]&key=[VOTRE_CLEF_API]. Du coup, pour effectuer ce type de recherche, vous devez connaitre l'identifiant de votre chaine. Pour trouver cet identifiant, à l'heure où j'écris ces lignes, cliquez en haut à droite sur l'image de votre chaine puis sélectionnez "Votre chaine". L'url vient de changer et est désormais de la forme https://www.youtube.com/channel/-y_Qbwg?.... Vous l'aurez compris, la référence de votre chaine correspond à ce qui est inscrit arpès channel/ .

Recherche par code région

Ce code région est plus utilisé pour restreindre les résultats d'une requête au niveau d'une région. Ces régions sont normées par l'Organisation Internationale de Standardisation (ISO) et correspondre essentiellement aux pays du monde.
La requête prend alors la forme suivante :
https://www.googleapis.com/youtube/v3/search?part=snippet&regionCode=fr&key=[VOTRE_CLEF_API]

Résultats les plus pertinents

Les résultats de recherches peuvent etre triés, mais peuvent aussis etre "triés" selon leur pertinence. Cette pertinence est gérée par les algorithmes de Google, l'utilisateur n'a aucune interaction possible sur ce type de tri.

Restriction des résultats

Tous les résultats retournés peuvent être restreints selon des critères définis. Youtube appelle ces critères des "filtres"

forContentOwner

Ce paramètre ne peut être utilisé que dans une demande dûment autorisée. Il est destiné exclusivement aux partenaires de contenu YouTube.
Le paramètre forContentOwner restreint la recherche pour récupérer uniquement les vidéos appartenant au propriétaire du contenu identifié par le paramètre onBehalfOfContentOwner. Si forContentOwner est défini sur true, la demande doit également répondre à ces exigences:

Le paramètre onBehalfOfContentOwner est requis.
L'utilisateur autorisant la demande doit utiliser un compte lié au propriétaire de contenu spécifié.
La valeur du paramètre de type doit être définie sur vidéo.
Aucun des autres paramètres suivants ne peut être défini: videoDefinition, videoDimension, videoDuration, videoLicense, videoEmbeddable, videoSyndicated, videoType.

forDeveloper

Ce paramètre ne peut être utilisé que dans une demande correctement autorisée et authentifiée. Le paramètre forDeveloper restreint la recherche pour récupérer uniquement les vidéos téléchargées via l'application ou le site Web du développeur. Le serveur API utilise les informations d'identification d'autorisation de la demande pour identifier le développeur. Le paramètre forDeveloper peut être utilisé en conjonction avec des paramètres de recherche facultatifs comme le paramètre q.
Pour cette fonctionnalité, chaque vidéo importée est automatiquement marquée avec le numéro de projet associé à l'application du développeur dans la Google Developers Console.
Lorsqu'une demande de recherche définit ultérieurement le paramètre forDeveloper à true, le serveur d'API utilise les informations d'identification d'autorisation de la demande pour identifier le développeur. Par conséquent, un développeur peut limiter les résultats aux vidéos téléchargées de sa propre application ou site Web, en excluant les vidéos téléchargées par d'autres applications ou sites.

forMine

Ce paramètre ne peut être utilisé que dans une demande correctement autorisée et authentifiée. Le paramètre forMine restreint la recherche aux vidéos appartenant à l'utilisateur authentifié. Si vous définissez ce paramètre sur true, la valeur du paramètre de type doit également être définie sur vidéo. De plus, aucun des autres paramètres suivants ne peut être défini dans la même demande: videoDefinition, videoDimension, videoDuration, videoLicense, videoEmbeddable, videoSyndicated, videoType.

relatedToVideoId

Le paramètre relatedToVideoId récupère une liste de vidéos liées à la vidéo identifiée par la valeur du paramètre. La valeur du paramètre doit être définie sur un ID vidéo YouTube et, si vous utilisez ce paramètre, le paramètre type doit être défini sur vidéo.

Videocaption

Le paramètre videoCaption indique si l'API doit filtrer les résultats de recherche vidéo en fonction de leur sous-titres. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Trois valeurs sont possibles :

any : Ne filtre pas les résultats en fonction de la disponibilité des sous-titres.
ClosedCaption : N'inclut que les vidéos qui ont des sous-titres.
aucun : n'inclut que les vidéos sans légende.

Exemple : https://www.googleapis.com/youtube/v3/search?q=aimant&part=snippet&videocaption=any&key=[VOTRE CLEF API]

VideoCategories

Le paramètre VideoCategories permet de lister les catégories associées à une vidéo.
https://www.googleapis.com/youtube/v3/videoCategories?part=snippet&id=e5G9oXVPdh4&key=[VOTRE CLEF API]
Lorsque la vidéo contient des termes/catégories associé(e)s, l'ensemble des termes associés se retrouvent dans le tableau items retourné.

Vidéodefinition

Le paramètre videodéfinition permet, vous l'aurez compris, de spécifier un critère de recherche concernant lé résolution des vidéos recherchées sur la plateforme Youtube. Ce paramètre vous permet de restreindre une recherche pour n'inclure que des vidéos haute définition (HD) ou définition standard (SD).
Les valeurs acceptables sont:

any : Renvoie toutes les vidéos, quelle que soit leur résolution.
élevé : Récupère uniquement les vidéos HD.
standard : Récupère uniquement les vidéos en définition standard.

D'autres paramètres optionnels peuvent être rajoutés à votre requête. Voyons les.

channelId

Le paramètre channelId indique que la réponse API ne doit contenir que des ressources créées par le canal.
Remarque: Les résultats de la recherche sont limités à un maximum de 500 vidéos si votre demande spécifie une valeur pour le paramètre channelId et définit la valeur du paramètre type sur video, mais elle ne définit pas également l'un des filtres forContentOwner, forDeveloper ou forMine.

channelType

Le paramètre channelType vous permet de restreindre une recherche à un type particulier de canal.
Les valeurs acceptables sont:

any - Renvoie toutes les chaînes.
show - Récupère uniquement les émissions.

eventType

Le paramètre eventType limite votre recherche aux événements de diffusion. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

completed : Recherche uniquement les diffusions terminées.
live : Recherche uniquement les diffusions actives.
upcoming : Inclure uniquement les diffusions à venir.

location

Le paramètre location, conjointement utilisé avec le paramètre locationRadius, définit une zone géographique circulaire et limite également la recherche aux vidéos qui spécifient, dans leurs métadonnées, un emplacement géographique qui se situe dans cette zone. La valeur du paramètre est une chaîne qui spécifie les coordonnées de latitude / longitude, par ex. (37,42307, -122,08427).
La valeur du paramètre de localisation identifie le point au centre de la zone.

Le paramètre locationRadius spécifie la distance maximale que l'emplacement associé à une vidéo peut être de ce point pour que la vidéo soit toujours incluse dans les résultats de la recherche.
L'API renvoie une erreur si votre demande spécifie une valeur pour le paramètre location mais ne spécifie pas également une valeur pour le paramètre locationRadius.

locationRadius

Le paramètre locationRadius, conjointement avec le paramètre location, définit une zone géographique circulaire.
La valeur du paramètre doit être un nombre à virgule flottante suivi d'une unité de mesure. Les unités de mesure valides sont m, km, ft et mi. Par exemple, les valeurs de paramètres valides incluent 1500 m, 5 km, 10000 pieds et 0,75 mi.
L'API ne prend pas en charge les valeurs des paramètres locationRadius supérieures à 1 000 kilomètres.
Remarque: Voir la définition du paramètre d'emplacement pour plus d'informations.

maxResults

Le paramètre maxResults spécifie le nombre maximal d'éléments qui doivent être renvoyés dans l'ensemble de résultats. Les valeurs acceptables sont comprises entre 0 et 50 inclus. La valeur par défaut est 5.

onBehalfOfContentOwner

Ce paramètre ne peut être utilisé que dans une demande correctement authentifiée. Remarque: ce paramètre est destiné exclusivement aux partenaires de contenu YouTube.
Le paramètre onBehalfOfContentOwner indique que les informations d'identification d'autorisation de la demande identifient un utilisateur YouTube qui agit au nom du propriétaire du contenu spécifié dans la valeur du paramètre. Ce paramètre est destiné aux partenaires de contenu YouTube qui possèdent et gèrent de nombreuses chaînes YouTube différentes. Il permet aux propriétaires de contenu de s'authentifier une fois et d'accéder à toutes leurs données vidéo et de chaîne, sans avoir à fournir les informations d'authentification pour chaque chaîne individuelle. Ce compte avec lequel l'utilisateur s'authentifie doit être lié au propriétaire de contenu YouTube spécifié.

order

Le paramètre order spécifie la méthode qui sera utilisée pour ordonner les résultats retournésI. La valeur par défaut est pertinence.
Les valeurs possibles sont:

date - Les résultats sont triés par ordre chronologique inverse en fonction de la date de leur création.
note - Les résultats sont triés de la note la plus élevée à la note la plus basse.
pertinence - Les résultats sont triés en fonction de leur pertinence pour la requête de recherche. Il s'agit de la valeur par défaut de ce paramètre.
title - Les résultats sont triés alphabétiquement par titre.
videoCount - Les chaînes sont triés par ordre décroissant de leur nombre de vidéos téléchargées.
viewCount - Les résultats sont triés du plus grand au plus petit nombre de vues. Pour les diffusions en direct, les vidéos sont triées par nombre de téléspectateurs simultanés pendant que les diffusions sont en cours.

pageToken

Le paramètre pageToken identifie une page spécifique dans le jeu de résultats renvoyés. Dans la réponse retournée, les propriétés nextPageToken et prevPageToken identifient d'autres pages pouvant être récupérées.

publishedAfter

Le paramètre publishedAfter indique que les résultats retournés ne doivent contenir que des ressources créées à ou après l'heure spécifiée. La valeur est une valeur date-heure formatée RFC 3339 (1970-01-01T00: 00: 00Z).

publishedBefore

Le paramètre publishedBefore indique que les résultats retournés ne doivent contenir que des ressources créées à ou avant l'heure spécifiée. La valeur est une valeur date-heure formatée RFC 3339 (1970-01-01T00: 00: 00Z).

q

Le paramètre q spécifie le terme de requête à rechercher.

Votre requête peut également utiliser les opérateurs booléens NOT (-) et OR (|) pour exclure des vidéos ou rechercher des vidéos associées à l'un des nombreux termes de recherche. Par exemple, pour rechercher des vidéos correspondant à "boating" ou "sailing", définissez la valeur du paramètre q sur boating|sailing. De même, pour rechercher des vidéos correspondant à "boating" ou "sailing" mais pas à "fishing", définissez la valeur du paramètre q sur navigation|navigation-fishing. Notez que le caractère de canal doit être échappé par URL lorsqu'il est envoyé dans votre demande d'API. La valeur d'échappement URL pour le caractère de canal est %7C.

regionCode

Le paramètre regionCode demande à l'API de renvoyer les résultats de recherche pour les vidéos pouvant être visionnées dans le pays spécifié. La valeur du paramètre est un code de pays ISO 3166-1 alpha-2.

relevanceLanguage

Le paramètre relevanceLanguage demande à l'API de renvoyer les résultats de recherche les plus pertinents pour la langue spécifiée. La valeur du paramètre est généralement un code de langue à deux lettres ISO 639-1. Cependant, vous devez utiliser les valeurs zh-Hans pour le chinois simplifié et zh-Hant pour le chinois traditionnel. Veuillez noter que les résultats dans d'autres langues seront toujours renvoyés s'ils sont très pertinents pour le terme de la requête de recherche.

safeSearch

Le paramètre safeSearch indique si les résultats de la recherche doivent inclure du contenu restreint ainsi que du contenu standard.
Les valeurs acceptables sont:

moderate : YouTube filtrera du contenu des résultats de recherche et, au moins, filtrera le contenu qui est restreint dans votre région. En fonction de leur contenu, les résultats de recherche peuvent être supprimés des résultats de recherche ou rétrogradés dans les résultats de recherche. Il s'agit de la valeur de paramètre par défaut.
none : YouTube ne filtrera pas l'ensemble des résultats de la recherche.
strict : YouTube essaiera d'exclure tout le contenu restreint de l'ensemble de résultats de recherche. En fonction de leur contenu, les résultats de recherche peuvent être supprimés des résultats de recherche ou rétrogradés dans les résultats de recherche.

topicId

Le paramètre topicId indique que la réponse de l'API ne doit contenir que des ressources associées à la rubrique spécifiée. La valeur identifie un ID de rubrique Freebase.
Important: en raison de la dépréciation de Freebase et de l'API Freebase, le paramètre topicId a commencé à fonctionner différemment à partir du 27 février 2017. Depuis, YouTube a commencé à prendre en charge un petit ensemble d'ID de sujet organisés, et vous ne pouvez utiliser que cet ensemble d'ID comme valeurs pour ce paramètre.

type

Le paramètre type restreint une requête de recherche pour récupérer uniquement un type particulier de ressource. La valeur est une liste de types de ressources séparés par des virgules. La valeur par défaut est vidéo, chaîne, liste de lecture.
Les valeurs acceptables sont:

channel
playlist
video

videoCaption

any : Ne filtre pas les résultats en fonction de la disponibilité des sous-titres.
ClosedCaption : N'inclut que les vidéos qui ont des sous-titres.
aucun: n'inclut que les vidéos sans sous-titres.

videoCategoryId

Le paramètre videoCategoryId filtre les résultats de recherche vidéo en fonction de leur catégorie. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.

videoDefinition

Le paramètre videoDefinition vous permet de restreindre une recherche pour n'inclure que des vidéos haute définition (HD) ou définition standard (SD). Les vidéos HD sont disponibles pour la lecture en au moins 720p, bien que des résolutions plus élevées, comme 1080p, puissent également être disponibles. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

any : Renvoie toutes les vidéos, quelle que soit leur résolution.
high: Récupère uniquement les vidéos HD.
standard: Récupère uniquement les vidéos en définition standard.

videoDimension

Le paramètre videoDimension vous permet de restreindre une recherche pour récupérer uniquement des vidéos 2D ou 3D. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

2D - Restreindre les résultats de recherche pour exclure les vidéos 3D.
3D - Limitez les résultats de recherche pour n'inclure que des vidéos 3D.
any - Incluez des vidéos 3D et non 3D dans les résultats renvoyés. Ceci est la valeur par défault.

videoDuration

Le paramètre videoDuration filtre les résultats de recherche vidéo en fonction de leur durée. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

any : Ne filtre pas les résultats de recherche vidéo en fonction de leur durée. Ceci est la valeur par défault.
long : Inclut uniquement les vidéos de plus de 20 minutes.
moyen : N'inclut que les vidéos d'une durée comprise entre quatre et 20 minutes (inclus).
court : N'inclut que des vidéos de moins de quatre minutes

videoEmbeddable

Le paramètre videoEmbeddable vous permet de restreindre une recherche aux seules vidéos pouvant être intégrées dans une page Web. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

any - Retourne toutes les vidéos, intégrables ou non.
true - Récupère uniquement les vidéos intégrables.

videoLicence

Le paramètre videoLicense filtre les résultats de recherche pour inclure uniquement les vidéos avec une licence particulière. YouTube permet aux téléverseurs de vidéos de choisir d'attacher la licence Creative Commons ou la licence YouTube standard à chacune de leurs vidéos. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

any : Renvoie toutes les vidéos, quelle que soit leur licence, qui correspondent aux paramètres de la requête.
creativeCommon : Renvoyez uniquement les vidéos disposant d'une licence Creative Commons. Les utilisateurs peuvent réutiliser des vidéos avec cette licence dans d'autres vidéos qu'ils créent. Apprendre encore plus.
youtube : Renvoyez uniquement les vidéos disposant de la licence YouTube standard.

videoSyndicated

Le paramètre videoSyndicated vous permet de restreindre une recherche aux seules vidéos pouvant être lues en dehors de youtube.com. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

any : Retourne toutes les vidéos, syndiquées ou non.
true : Récupère uniquement les vidéos syndiquées.

videoType

Le paramètre videoType vous permet de restreindre une recherche à un type particulier de vidéos. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre de type sur vidéo.
Les valeurs acceptables sont:

any : Retourne toutes les vidéos.
episode : Récupère uniquement les épisodes d'émissions.
movie : Récupère uniquement les films.

Trier les résultats retournés

Nous l'avons déjà survolé au travers des API sur les recherches, les résultats retournés peuvent etre triés avant d'être retournés aux utilisateurs. Les résultats retournés par l'outil de recherche peuvent etre triés. Pour effectuer ces tris, il suffit de rajouter dans l'URL le "champs" sur lequel effectuer le tri, en rajoutant à l'URL le paramètre &order=[champs]. [champs] peut prendre comme valeur

date : Le tri est effectué sur la date.
rating : le tri est effectué selon les notation des vidéos par les utilisateurs. Les vidéos les plus populaire sont les premières retournées.
relevance : le tri est effectué sur la pertinence des vidéos. (selon Youtube)
title : le tri des résultats est effectué sur le titre des vidéos
videoCount : le tri est effectué sur le nombre de vidéos par canal
viewcount : le tri est effectué selon le nombre de vue

Les souscriptions

Il est aussi possible d'afficher les souscriptions à un canal. Je vous donnee la façon de faire mas je n'ai pas réussi à le faire.
Nous essayerons de creuser ce sujest ultérieurement lorsque nous verrons plus en détail les souscriptions. En effet, meme si cette API est accessible via une recherche, un pan complet de l'API de youtub est dédié aux souscriptions/abonnements. Nous regarderon plus en détail à ce moment 14. Meta données de mon channel ID 15.

API Youtube (N°3) : les recherches