Vous déposez un lien YouTube dans l’éditeur, cela fonctionne. Mais lorsque vous avez besoin d’une playlist entière sur votre site, qui intègre automatiquement les nouvelles vidéos, copier les liens manuellement à chaque fois devient vite fastidieux.

Un script en PHP avec l’API YouTube Data v3 règle complètement le problème: il récupère toutes les vidéos d’une playlist publique, renvoie du JSON, et vous les affichez comme vous le souhaitez, sous forme de grille de cartes, de liste, de galerie. La mise en place prend 15 minutes, vous avez seulement besoin d’une clé d’API et de connaissances de base en PHP.

Voici un code fonctionnel pour WordPress avec gestion des erreurs, pagination et mise en cache. L’approche est universelle: elle fonctionne dans tout projet PHP, pas uniquement sous WP.

💡 Aperçu rapide:

• Créez une clé d’API dans la Google Cloud Console et associez-la à l’API YouTube Data v3
• Envoyez une requête à playlistItems et obtenez un JSON contenant toutes les vidéos de la playlist
• Analysez la réponse, récupérez les vignettes et les liens, affichez-les dans une grille sur la page
• Ajoutez la pagination pour les playlists de plus de 50 vidéos et la mise en cache via set_transient()

Étape 1: Créer une clé d’API YouTube Data v3

Une clé d’API identifie votre application auprès de YouTube et suit les quotas. Elle se crée gratuitement, la limite quotidienne est de 10 000 unités. Une seule clé est largement suffisante pour la plupart des sites.

Rendez-vous sur la Google Cloud Console avec votre compte Google. Créez un nouveau projet, le bouton de sélection de projet se trouve dans la barre supérieure, puis Nouveau projet. Donnez-lui un nom explicite, par exemple my-youtube-feed.

Une fois le projet créé, allez dans API et services → Bibliothèque. Dans la barre de recherche, tapez YouTube Data API v3 et cliquez sur Activer. Sans cette étape, la clé ne sera pas liée à la bonne API et les requêtes renverront une erreur 403.

Maintenant, la clé elle-même. Dans le menu latéral, ouvrez Identifiants, cliquez sur Créer des identifiants → Clé API. Le système génère une clé et l’affiche dans une fenêtre modale. Copiez-la immédiatement: après avoir fermé la fenêtre, la clé reste visible dans la liste, mais sa valeur est partiellement masquée.

Veillez à cliquer sur Restreindre la clé. Dans la section Restrictions d’API, sélectionnez YouTube Data API v3, ainsi la clé ne fonctionnera pas pour d’autres API même si elle se retrouve dans un dépôt public. Pour le développement local, le référent HTTP peut rester vide.

La clé ressemble à AIzaSyD-.... Enregistrez-la dans wp-config.php via define('YOUTUBE_API_KEY', '...') et ajoutez wp-config.php au .gitignore. Ne codez pas la clé en dur dans le code du thème.

Étape 2: Récupérer les vidéos d’une playlist

Pour la requête, vous avez besoin de deux éléments: une clé d’API et l’identifiant de la playlist. L’identifiant s’extrait de l’URL: ouvrez la playlist sur YouTube, copiez l’adresse dans la barre. Le paramètre list= dans l’URL est l’identifiant de la playlist: par exemple, PLp0YhAQYkolGq1e6r1m5....

Requête PHP de base vers le point de terminaison playlistItems:

1
$api_key     = 'AIzaSy...';          // your key from step 1
2
$playlist_id = 'PLp0YhAQYkolG...';   // playlist ID from URL
3
 
4
$api_url = 'https://www.googleapis.com/youtube/v3/playlistItems' .
5
    '?part=snippet' .
6
    '&maxResults=50' .
7
    '&playlistId=' . urlencode($playlist_id) .
8
    '&key=' . $api_key;
9
 
10
$response = file_get_contents($api_url);
11
$data     = json_decode($response, true);
12
 
13
if (json_last_error() !== JSON_ERROR_NONE) {
14
    die('JSON parsing error: ' . json_last_error_msg());
15
}

Voici ce qui se passe. part=snippet demande les données de base: titre, description, vignette, position dans la playlist. Pour un jeu complet, vous pouvez spécifier snippet,contentDetails,status. maxResults=50 est le maximum par requête, l’API renvoie 5 enregistrements par défaut, il est donc préférable de préciser le paramètre explicitement. Encodez playlistId via urlencode() en cas de caractères spéciaux.

Pour la production, remplacez file_get_contents() par wp_remote_get() (dans WordPress) ou cURL avec un délai d’expiration. Un appel direct échouera si Google est temporairement indisponible ou si le réseau est lent. Voici une version avec gestion des erreurs HTTP:

1
$response = wp_remote_get($api_url, [
2
    'timeout' => 15,
3
    'headers' => ['Accept' => 'application/json'],
4
]);
5
 
6
if (is_wp_error($response)) {
7
    error_log('YouTube API error: ' . $response->get_error_message());
8
    return [];
9
}
10
 
11
$http_code = wp_remote_retrieve_response_code($response);
12
if ($http_code !== 200) {
13
    error_log('YouTube API HTTP ' . $http_code);
14
    return [];
15
}
16
 
17
$body = wp_remote_retrieve_body($response);
18
$data = json_decode($body, true);

Deux niveaux de vérification: d’abord is_wp_error() intercepte les échecs réseau, ensuite nous vérifions le code HTTP. Si quelque chose ne va pas, nous renvoyons un tableau vide, le site ne plante pas.

Étape 3: Afficher la liste de vidéos sur une page

L’API renvoie un tableau items. Chaque élément correspond à une vidéo de la playlist. Structure de la réponse:

1
{
2
  "items": [
3
    {
4
      "snippet": {
5
        "title": "Video title",
6
        "description": "Description...",
7
        "thumbnails": {
8
          "default":  { "url": "https://i.ytimg.com/.../default.jpg" },
9
          "medium":   { "url": "https://i.ytimg.com/.../mqdefault.jpg" },
10
          "high":     { "url": "https://i.ytimg.com/.../hqdefault.jpg" }
11
        },
12
        "resourceId": {
13
          "videoId": "dQw4w9WgXcQ"
14
        }
15
      }
16
    }
17
  ]
18
}

Une vidéo est identifiée par resourceId.videoId. À partir de cet identifiant, on construit le lien https://www.youtube.com/watch?v=<videoId>. Les vignettes se trouvent dans thumbnails à trois résolutions: pour une grille de cartes, prenez medium, pour une liste compacte, default.

Code d’affichage pour WordPress, shortcode ou template de page:

1
if (! empty($data['items'])) {
2
    echo '<div class="yt-playlist-grid">';
3
 
4
    foreach ($data['items'] as $item) {
5
        $title     = esc_html($item['snippet']['title']);
6
        $video_id  = esc_attr($item['snippet']['resourceId']['videoId']);
7
        $thumbnail = esc_url($item['snippet']['thumbnails']['medium']['url']);
8
        $link      = 'https://www.youtube.com/watch?v=' . $video_id;
9
 
10
        printf(
11
            '<a href="%s" class="yt-card" target="_blank" rel="noopener">'
12
            . '<img src="%s" alt="%s" loading="lazy">'
13
            . '<span>%s</span></a>',
14
            $link, $thumbnail, $title, $title
15
        );
16
    }
17
 
18
    echo '</div>';
19
}

Trois points qui font gagner du temps de débogage:

• loading="lazy". Avec 50 vidéos sur une page sans lazy loading, le PageSpeed chutera. L’attribut indique au navigateur: ne chargez l’image que lorsqu’elle devient visible par défilement.
• esc_html()** et esc_url().** Assainissement obligatoire pour WordPress. Les titres des vidéos contiennent parfois des guillemets et des entités HTML, sans échappement ils casseront la mise en page.
• target="_blank"** avec rel="noopener".** Ouvrez YouTube dans un nouvel onglet, mais sans lui donner accès à window.opener, protection contre le tab-napping.

CSS pour la grille, minimal, pour un thème standard:

1
.yt-playlist-grid {
2
    display: grid;
3
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
4
    gap: 20px;
5
}
6
.yt-card {
7
    text-decoration: none;
8
    color: inherit;
9
    border-radius: 8px;
10
    overflow: hidden;
11
    transition: transform 0.2s;
12
}
13
.yt-card:hover {
14
    transform: translateY(-2px);
15
}
16
.yt-card img {
17
    width: 100%;
18
    aspect-ratio: 16 / 9;
19
    object-fit: cover;
20
}
21
.yt-card span {
22
    display: block;
23
    padding: 10px;
24
    font-weight: 600;
25
    font-size: 14px;
26
}

La grille s’adapte automatiquement à la largeur de l’écran: auto-fill + minmax(280px, 1fr) donnent d’une à plusieurs colonnes sans media queries.

Étape 4: Pagination, quotas et erreurs courantes

Pagination. Une requête renvoie au maximum 50 vidéos. S’il y en a plus dans la playlist, un champ nextPageToken apparaît dans la réponse. Passez-le dans la requête suivante, l’API renverra la page suivante. Boucle:

1
$all_items  = [];
2
$page_token = null;
3
 
4
do {
5
    $url = $api_url . '&pageToken=' . urlencode($page_token ?? '');
6
    // ... API request ...
7
    $all_items  = array_merge($all_items, $data['items'] ?? []);
8
    $page_token = $data['nextPageToken'] ?? null;
9
} while ($page_token && count($all_items) < 500);

La boucle s’arrête à 500 vidéos, un plafond raisonnable pour une page de site. Sans limite, vous risquez d’épuiser tout le quota en quelques chargements.

Quotas. Chaque appel playlistItems.list coûte 1 unité de quota, ceci est confirmé par le tableau officiel des quotas de Google. La limite quotidienne est de 10 000 unités. Cela représente 10 000 requêtes par jour, bien plus qu’il n’en faut pour la grande majorité des sites. Mais si la playlist se met à jour fréquemment, ajoutez une mise en cache:

1
$cache_key   = 'yt_playlist_' . md5($playlist_id);
2
$cached_data = get_transient($cache_key);
3
 
4
if ($cached_data !== false) {
5
    return $cached_data;
6
}
7
 
8
// ... API request ...
9
 
10
set_transient($cache_key, $data, HOUR_IN_SECONDS * 6);

Six heures est un bon équilibre entre fraîcheur et économie de quota. Pour des playlists non critiques, réglez sur 12 à 24 heures. get_transient() et set_transient() sont des fonctions natives de WordPress, elles fonctionnent avec le cache objet (Redis/Memcached) s’il est configuré, sinon elles écrivent dans wp_options.

Erreurs courantes et comment les résoudre:

• 403 Forbidden. L’API n’est pas activée pour le projet dans la Google Cloud Console. Revenez à l’étape 1: le bouton Activer pour YouTube Data API v3 doit être cliqué. Vérifiez aussi s’il y a une restriction IP dans les paramètres de la clé.
• 400 Bad Request, «API key not valid». La clé vient d’être créée et n’est pas encore active. Attendez 2 à 5 minutes: les restrictions d’API ne se propagent pas instantanément.
• 404 Not Found. Identifiant de playlist invalide, ou la playlist est privée. Une clé d’API ne renvoie que les playlists publiques et non répertoriées. Les playlists privées nécessitent une autorisation OAuth.
• Tableau items vide avec un identifiant valide. Le plus probable est que la playlist soit vide. Ouvrez l’URL de la playlist dans un navigateur et assurez-vous qu’elle contient des vidéos.

💻 Vidéo: L’API YouTube Data v3 en action

Une courte vidéo sur le sujet, qui montre visuellement tout le processus, de la création de la clé à l’affichage de la liste de vidéos:

⁉️🤔 Foire aux questions

L’API fonctionne-t-elle avec les playlists privées?

Non. playlistItems.list avec une clé d’API ne renvoie que les playlists publiques et non répertoriées. Pour les playlists privées, vous avez besoin d’une autorisation OAuth: l’utilisateur doit explicitement accorder à votre application l’accès à son compte. Pour un site agrégateur public, une clé d’API suffit.

Puis-je récupérer les vidéos de la playlist de quelqu’un d’autre?

Oui, si la playlist est publique. Une clé d’API n’est pas liée au propriétaire de la playlist, elle identifie votre application, pas l’utilisateur YouTube. Toute playlist publique est accessible par son identifiant, peu importe qui l’a créée.

Comment obtenir plus de 50 vidéos en une seule fois?

Vous ne pouvez pas, c’est une limite stricte de maxResults pour playlistItems, fixée dans la documentation de Google. Utilisez la pagination via nextPageToken (étape 4). Pour une playlist de 300 vidéos, vous aurez besoin de 6 requêtes séquentielles, qui dépenseront ensemble 6 unités de quota sur les 10 000 quotidiennes.

Pourquoi les vignettes des vidéos ne s’affichent-elles pas?

Vérifiez l’URL dans thumbnails: le champ s’appelle url, pas link ni src. Deuxième raison, les bloqueurs de publicité coupent parfois le domaine i.ytimg.com. Troisième raison: certaines anciennes vidéos (avant 2010) n’ont pas de vignettes haute résolution, prenez default, elle est toujours présente.

Que faire si la clé est compromise?

Allez immédiatement dans Google Cloud Console → Identifiants, trouvez la clé et cliquez sur Supprimer. Créez-en une nouvelle. L’ancienne clé est désactivée en 5 minutes. Stockez la clé via define('YOUTUBE_API_KEY', '...') dans wp-config.php et excluez ce fichier du dépôt via .gitignore.

Cela vaut-il la peine de passer par l’API alors qu’on peut simplement coller un lien de playlist?

Si une playlist statique via iframe suffit pour le site, vous n’avez pas besoin de l’API, YouTube fournit un code d’intégration prêt à l’emploi. Mais dès que vous devez intégrer automatiquement les nouvelles vidéos, filtrer par date, personnaliser la mise en page ou afficher les vignettes dans un design non standard, l’API devient la seule option viable.

Pour un site WordPress, la combinaison wp_remote_get() + set_transient() élimine complètement les problèmes de quota et de vitesse: toutes les quelques heures, le script récupère le JSON, le met en cache, et le frontend travaille avec le cache instantanément. La playlist se met à jour toute seule, l’éditeur n’a rien à cliquer.

Si votre thème prend en charge le PHP personnalisé dans les templates, prenez le code de l’étape 3, adaptez le CSS à votre design. Si vous utilisez un constructeur de pages, encapsulez la logique PHP dans un shortcode et insérez-le n’importe où via [youtube_playlist id="PLp0..."].

Essayez avec une playlist: 15 minutes pour une clé et la première requête, et vous verrez si l’approche fonctionne pour votre besoin. Et si vous avez déjà utilisé l’API pour d’autres usages, écrivez en commentaire quel point de terminaison s’est avéré le plus utile.