Votre site a besoin d’un flux de vidéos YouTube, mais il n’existe pas de plugin prêt à l’emploi pour cette tâche et vous vous imaginez déjà une semaine de lutte avec OAuth, des jetons et des bibliothèques maladroites. L’API YouTube Data v3 permet de réaliser ce travail en une heure environ. Pas d’OAuth, pas de jeton utilisateur, pas de dépendance externe. Juste une clé d’API et une URL correctement construite.

Le point de terminaison de recherche renvoie des vidéos, des chaînes et des playlists par mots-clés. Il filtre par date, durée et chaîne. Il trie par pertinence ou par nombre de vues. En pratique, cela couvre la plupart des scénarios, du flux vidéo d’une chaîne spécifique à une compilation de «tutoriels wordpress» du mois écoulé.

Voici un guide étape par étape avec des exemples de requêtes en direct et du code PHP. À la fin, vous disposerez d’un module de recherche fonctionnel: du JSON structuré en entrée, une galerie vidéo en sortie, sans aucune bibliothèque tierce.

💡 Aperçu rapide:

• Créez un projet dans la console Google Cloud, activez l’API YouTube Data v3 et obtenez une clé d’API.
• Construisez l’URL de la requête de recherche: point de terminaison /youtube/v3/search, paramètres obligatoires part=snippet, key et q (depuis juin 2025, q est obligatoire; sans lui, l’API renvoie un tableau vide).
• Ajoutez des filtres: type (video/channel/playlist), channelId, publishedAfter/publishedBefore, maxResults, order, videoDuration, videoEmbeddable.
• Exécutez la requête via cURL en PHP, analysez la réponse JSON, affichez les résultats et mettez en place une mise en cache via les transients de WordPress.

Étape 1: Obtenir votre clé d’API

Sans clé, aucune requête API ne part. La clé est liée à un projet dans la console Google Cloud et identifie votre application; rien de plus compliqué qu’une connexion à un compte Google n’est nécessaire.

Voici la marche à suivre:

• Ouvrez la console Google Cloud et créez un nouveau projet ou sélectionnez-en un existant.
• Allez dans API et services → Bibliothèque, recherchez «YouTube Data API v3» et cliquez sur Activer.
• Ouvrez API et services → Identifiants, cliquez sur Créer des identifiants → Clé d’API.
• Copiez la clé. Définissez immédiatement une restriction: Restreindre la clé → YouTube Data API v3, afin que la clé ne puisse pas être utilisée pour d’autres services Google.

La clé se présente sous la forme d’une chaîne comme AIzaSyD-... et est transmise dans chaque requête via le paramètre key. Pour la recherche de vidéos publiques, cela suffit; OAuth n’est pas nécessaire. En revanche, si vous prévoyez des requêtes pour le compte d’un utilisateur (mise en ligne de vidéos, gestion de playlists), vous aurez besoin d’OAuth 2.0.

Test rapide: envoyez une requête GET au point de terminaison search avec un terme de recherche quelconque. Si vous recevez du JSON avec un tableau items, la clé fonctionne.

Étape 2: URL de la requête de recherche et paramètres obligatoires

Point de terminaison pour la recherche:

1
GET https://www.googleapis.com/youtube/v3/search

Deux paramètres sont toujours obligatoires:

Le paramètre q accepte du texte libre, exactement comme la barre de recherche sur youtube.com. Vous pouvez passer plusieurs mots séparés par des espaces ou des signes plus: q=wordpress+speed+optimization. La casse n’a pas d’importance.

Requête minimale fonctionnelle:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress&key=YOUR_KEY

Elle renverra 5 résultats (la valeur par défaut), ce que l’API retourne lorsque maxResults n’est pas surchargé.

Le paramètre type restreint le type de ressource recherchée:

• video, vidéos uniquement;
• channel, chaînes uniquement;
• playlist, playlists uniquement.

Vous pouvez lister plusieurs valeurs séparées par des virgules: type=video,channel. S’il est omis, l’API recherche tout. Les paramètres restants sont optionnels, mais ils transforment une requête brute en un outil précis.

Étape 3: Rechercher des vidéos par mots-clés

Un scénario classique: un utilisateur saisit une expression de recherche sur votre site, vous l’envoyez à l’API YouTube et affichez une sélection de vidéos.

Exemple de requête pour rechercher des vidéos avec le mot «swimming»:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=swimming&type=video&key=YOUR_KEY

La réponse arrive en JSON. Dans items[] se trouve un tableau des ressources trouvées. Pour chaque vidéo, vous avez:

• id.videoId, l’identifiant unique (à insérer dans https://www.youtube.com/watch?v=...);
• snippet.title, le titre de la vidéo;
• snippet.description, la description;
• snippet.thumbnails, des aperçus en plusieurs résolutions (default, medium, high);
• snippet.channelTitle, le nom de la chaîne.

En PHP, le moyen le plus simple de récupérer la réponse est file_get_contents. Voici un code de traitement minimal:

1
$apiKey = 'YOUR_KEY';
2
$query  = 'swimming';
3
$url    = "https://www.googleapis.com/youtube/v3/search?part=snippet&q={$query}&type=video&key={$apiKey}";
4
 
5
$response = file_get_contents($url);
6
$data     = json_decode($response, true);
7
 
8
foreach ($data['items'] as $item) {
9
    echo '<h3>' . htmlspecialchars($item['snippet']['title']) . '</h3>';
10
    echo '<p>' . htmlspecialchars($item['snippet']['description']) . '</p>';
11
    echo '<img src="' . $item['snippet']['thumbnails']['medium']['url'] . '" alt="">';
12
    echo '<a href="https://www.youtube.com/watch?v=' . $item['id']['videoId'] . '">Watch</a>';
13
}

file_get_contents convient pour les tests et les petits projets. En production, utilisez cURL: cela vous donne le contrôle sur les délais d’attente, les en-têtes et la gestion des erreurs. Et oui, si allow_url_fopen est désactivé sur votre hébergement, file_get_contents ne fonctionnera pas pour les URL externes. Dans ce cas, cURL est votre seule option.

Étape 4: Récupérer les vidéos d’une chaîne spécifique

Pour collecter toutes les vidéos d’une chaîne, passez le paramètre channelId. Trouver l’identifiant de la chaîne est facile: ouvrez la page de la chaîne sur YouTube et copiez la valeur après /channel/ dans la barre d’adresse (par exemple UC3VyA8KN_VgCF93EurnAQXw).

Requête:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UC3VyA8KN_VgCF93EurnAQXw&type=video&order=date&key=YOUR_KEY

Le paramètre order=date trie par date de publication, de la plus récente à la plus ancienne. Sans lui, l’API renvoie les résultats les plus pertinents, mais pour le flux d’une chaîne, l’ordre chronologique est plus logique.

La même requête en PHP avec cURL et une gestion basique des erreurs:

1
$apiKey    = 'YOUR_KEY';
2
$channelId = 'UC3VyA8KN_VgCF93EurnAQXw';
3
$url       = "https://www.googleapis.com/youtube/v3/search?part=snippet&channelId={$channelId}&type=video&order=date&key={$apiKey}";
4
 
5
$ch = curl_init();
6
curl_setopt_array($ch, [
7
    CURLOPT_URL            => $url,
8
    CURLOPT_RETURNTRANSFER => true,
9
    CURLOPT_TIMEOUT        => 15,
10
    CURLOPT_SSL_VERIFYPEER => true,
11
]);
12
 
13
$response = curl_exec($ch);
14
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
15
curl_close($ch);
16
 
17
if ($httpCode !== 200) {
18
    echo 'Request error. Code: ' . $httpCode;
19
    exit;
20
}
21
 
22
$data = json_decode($response, true);
23
 
24
foreach ($data['items'] as $item) {
25
    printf(
26
        '<div><a href="https://www.youtube.com/watch?v=%s">%s</a></div>',
27
        $item['id']['videoId'],
28
        htmlspecialchars($item['snippet']['title'])
29
    );
30
}

Une chaîne peut avoir des centaines de vidéos, mais une seule requête ne renvoie pas plus de 50 résultats. Pour tout récupérer, utilisez le champ pageToken de la réponse de l’API: passez sa valeur dans la requête suivante en tant que pageToken=<token>. Répétez jusqu’à ce que nextPageToken soit vide.

Étape 5: Limites, tri et quotas

Sur un site réel, vous avez rarement besoin de «toutes les vidéos pour une requête». Le plus souvent, vous voulez le top 10 du mois écoulé ou une sélection qui exclut les Shorts. Pour cela, l’API fournit cinq paramètres de réglage fin.

maxResults: combien d’éléments renvoyer. Valeurs valides: de 1 à 50. La valeur par défaut est 5. Pour une galerie ou un flux, définissez 20 à 30, mais gardez les quotas à l’esprit.

order: champ de tri:

publishedAfter** / **publishedBefore: filtrer par date de publication. Format: ISO 8601 (RFC 3339). Exemple: publishedAfter=2026-01-01T00:00:00Z. Permet d’écarter les vidéos archivées lorsque vous avez seulement besoin de contenu récent.

videoDuration: filtrer par durée:

• short, moins de 4 minutes;
• medium, de 4 à 20 minutes;
• long, plus de 20 minutes;
• non spécifié, toutes les durées.

videoEmbeddable avec la valeur true sélectionne uniquement les vidéos dont l’intégration est autorisée sur des sites tiers. Pour un site qui intègre le lecteur YouTube, c’est un paramètre indispensable.

Requête combinée: 10 vidéos intégrables sur WordPress, pas antérieures à 2026, d’une durée supérieure à 4 minutes, triées par nombre de vues:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress+tutorial&type=video&videoEmbeddable=true&videoDuration=medium&publishedAfter=2026-01-01T00:00:00Z&maxResults=10&order=viewCount&key=YOUR_KEY

Quotas: comment éviter un écran vide

Chaque appel search.list coûte 100 unités de votre quota quotidien. Par défaut, un projet Google Cloud reçoit gratuitement 10 000 unités par jour, soit environ 100 appels de recherche. Pour un site avec plus d’une centaine de visiteurs par jour, cela ne suffit pas.

La solution consiste à mettre en cache les réponses de l’API. Dans WordPress, les transients fonctionnent parfaitement pour cela:

1
$cache_key = 'yt_search_' . md5($query);
2
$videos    = get_transient($cache_key);
3
 
4
if ($videos === false) {
5
    $response = wp_remote_get($url);
6
    $body     = json_decode(wp_remote_retrieve_body($response), true);
7
    $videos   = $body['items'] ?? [];
8
 
9
    set_transient($cache_key, $videos, 6 * HOUR_IN_SECONDS);
10
}
11
 
12
// Display $videos in a gallery...

Un transients de six heures signifie un maximum de 4 requêtes API par jour pour une seule expression de recherche. Même avec dix requêtes différentes réparties sur les pages du site, vous restez sous la barre des 40 appels, soit moins de la moitié du quota quotidien. Si vous avez besoin de plus, demandez une augmentation de quota via la console Google Cloud: Quotas → YouTube Data API v3 → Modifier.

L’exemple en direct ci-dessus montre comment construire une galerie vidéo de chaîne via l’API Data v3 en PHP en 15 minutes.

⁉️🤔 Foire aux questions

OAuth est-il nécessaire pour rechercher des vidéos via l’API YouTube?

Non. Pour les requêtes de recherche vers /youtube/v3/search, une clé d’API suffit. OAuth n’est requis que pour les opérations au niveau de l’utilisateur: mise en ligne de vidéos, gestion des playlists, abonnements. Une clé d’API s’obtient dans la console Google Cloud en quelques minutes et s’utilise immédiatement.

Combien de requêtes par jour peut-on faire gratuitement?

Chaque projet Google Cloud reçoit gratuitement 10 000 unités de quota par jour. Un appel search.list coûte 100 unités, donc environ 100 requêtes de recherche par jour. Avec une mise en cache via les transients de WordPress, cela suffit pour un site moyen. Si vous avez besoin de plus, demandez une augmentation de quota via la console Google Cloud (section Quotas).

Comment obtenir plus de 50 résultats à partir d’une seule requête?

Par la pagination. Dans la réponse JSON, l’API renvoie un champ nextPageToken. Passez sa valeur comme paramètre pageToken dans la requête suivante pour obtenir la page suivante. Répétez jusqu’à ce que nextPageToken soit vide. Un parcours complet d’une chaîne de 500 vidéos nécessite 10 requêtes et 1 000 unités de quota.

Puis-je rechercher des vidéos dans d’autres langues que l’anglais?

Oui. Le paramètre q accepte n’importe quelle langue, y compris le français. L’algorithme de recherche de YouTube détermine automatiquement la pertinence linguistique. Pour forcer un affinage, ajoutez le paramètre relevanceLanguage=ru; les résultats seront classés en faveur du contenu en langue russe.

Pourquoi l’API renvoie-t-elle un tableau vide alors que la requête est correcte?

La cause la plus fréquente: publishedAfter est défini sur une date future ou sur la date du jour avec une heure exacte. Utilisez le début de la journée: T00:00:00Z. La deuxième cause: une combinaison de filtres qui exclut tous les résultats. Par exemple, videoDuration=long et videoEmbeddable=true associés au channelId d’une petite chaîne peuvent ne donner aucune correspondance. Simplifiez la requête jusqu’à part=snippet&q=...&key=... et ajoutez les filtres un par un, en vérifiant les résultats à chaque étape.

Construire une recherche en une heure: quels outils pour quelle tâche

Votre choix d’outils dépend de ce que vous construisez exactement. Si vous avez besoin d’une simple galerie vidéo pour une chaîne sur un petit site d’entreprise, prenez un wrapper PHP prêt à l’emploi comme madcoda/php-youtube-api: un package Composer, trois lignes de code, résultat en cinq minutes. Si vous construisez une recherche personnalisée avec des filtres, de la mise en cache et de la pagination, écrivez votre propre gestionnaire en utilisant cURL et les transients de WordPress. Pour un site à fort trafic avec des dizaines de milliers de visiteurs, ajoutez une couche de cache Redis par-dessus les transients et mettez en place une synchronisation en arrière-plan via WP-Cron; les pages se chargent alors en millisecondes et les quotas API ne sont dépensés que pour l’invalidation du cache.

Vous avez déjà votre clé d’API. La mise en cache est configurée. Il ne reste plus qu’à assembler l’URL correspondant à votre tâche et à écrire la boucle d’affichage. Le résultat est un flux vidéo en direct qui ne dépend pas de services tiers et ne dépasse pas les limites de quota.