API Cinéma

Afficher les séances d’un cinéma sur WordPress

Un petit plugin WordPress avec un shortcode qui affiche le programme d’un cinéma pour les jours qui viennent, à jour et mis en cache, en 80 lignes de PHP.

4 min de lecture

Sur cette page
  1. Ce qu’il vous faut
  2. 1.Ranger la clé dans wp-config.php
  3. 2.Créer le plugin
  4. 3.Comment ça marche
  5. 4.L’utiliser
  6. 5.Un peu de style
  7. Pour aller plus loin

Cinémas, ciné-clubs, sites d’actualité locale et offices de tourisme tournent souvent sous WordPress et veulent afficher un programme qui se met à jour tout seul. Ce tutoriel construit un petit plugin qui ajoute un shortcode :

[cinema_showtimes cinema="le-champo-paris-5e-arrondissement"]

Il affiche les séances du cinéma pour les jours qui viennent, film par film, chaque horaire menant à la page de réservation du cinéma. Environ 80 lignes de PHP, sans dépendance.

Ce qu’il vous faut

  • Un site WordPress où vous pouvez ajouter un plugin (FTP, SFTP ou gestionnaire de fichiers de l’hébergeur).
  • Une clé API Cinéma : créez un compte gratuit, confirmez votre adresse e-mail, puis créez une clé depuis le tableau de bord. L’offre gratuite (150 requêtes par semaine) suffit pour essayer ou pour un site non commercial, grâce au cache décrit plus bas ; le site d’un cinéma ou d’une entreprise nécessite un forfait payant, dès 12 € par mois.
  • Le slug du cinéma. Cherchez-le par son nom :
Terminal
curl "https://api.api-cinema.com/v1/cinemas?q=champo" -H "Authorization: Bearer ac_live_…"

La réponse donne "slug": "le-champo-paris-5e-arrondissement". Tout cinéma français ou américain de l’API marche de la même façon.

Ranger la clé dans wp-config.php

La clé doit rester sur le serveur. Ajoutez cette ligne dans wp-config.php, au-dessus de /* C’est tout, ne touchez pas à ce qui suit ! */ :

PHP
define('API_CINEMA_KEY', 'ac_live_…');

Créer le plugin

Créez le dossier wp-content/plugins/api-cinema-showtimes/ et, dedans, le fichier api-cinema-showtimes.php :

PHP
<?php
/**
 * Plugin Name: API Cinéma showtimes
 * Description: [cinema_showtimes cinema="le-champo-paris-5e-arrondissement"] affiche le programme d’un cinéma pour les jours qui viennent.
 * Version: 1.0.0
 */

if (!defined('ABSPATH')) {
    exit;
}

add_shortcode('cinema_showtimes', 'api_cinema_showtimes_shortcode');

function api_cinema_showtimes_shortcode($atts)
{
    $atts = shortcode_atts(['cinema' => '', 'days' => 7], $atts, 'cinema_showtimes');
    $cinema = sanitize_title($atts['cinema']);
    $days = max(1, min(14, (int) $atts['days']));
    if ($cinema === '' || !defined('API_CINEMA_KEY')) {
        return '';
    }

    $showtimes = api_cinema_fetch_showtimes($cinema, $days);
    if ($showtimes === null) {
        return '<p class="cinema-showtimes">Programme momentanément indisponible.</p>';
    }
    if (!$showtimes) {
        return '<p class="cinema-showtimes">Aucune séance dans les jours qui viennent.</p>';
    }
    return api_cinema_render_showtimes($showtimes);
}

/** Séances à venir d’un cinéma, gardées en cache deux heures ; null si l’API ne répond pas. */
function api_cinema_fetch_showtimes($cinema, $days)
{
    $cache_key = 'api_cinema_' . md5($cinema . '|' . $days);
    $cached = get_transient($cache_key);
    if ($cached !== false) {
        return $cached;
    }

    $url = add_query_arg([
        'to' => wp_date('Y-m-d', strtotime('+' . ($days - 1) . ' days')),
        'include' => 'movie',
        'limit' => 1000,
    ], 'https://api.api-cinema.com/v1/cinemas/' . rawurlencode($cinema) . '/showtimes');

    $response = wp_remote_get($url, [
        'headers' => ['Authorization' => 'Bearer ' . API_CINEMA_KEY],
        'timeout' => 10,
    ]);
    if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {
        return null;
    }

    $body = json_decode(wp_remote_retrieve_body($response), true);
    $showtimes = $body['data'] ?? [];
    set_transient($cache_key, $showtimes, 2 * HOUR_IN_SECONDS);
    return $showtimes;
}

/** Jour par jour, film par film, chaque horaire menant à la réservation quand elle existe. */
function api_cinema_render_showtimes($showtimes)
{
    $days = [];
    foreach ($showtimes as $s) {
        $day = substr($s['startsAt'], 0, 10);
        $film = $s['movie']['title'];
        $days[$day][$film][] = $s;
    }

    $html = '<div class="cinema-showtimes">';
    foreach ($days as $day => $films) {
        $html .= '<h3>' . esc_html(wp_date('l j F', strtotime($day . 'T12:00:00'))) . '</h3><ul>';
        foreach ($films as $film => $times) {
            $html .= '<li><strong>' . esc_html($film) . '</strong> ';
            foreach ($times as $s) {
                $label = substr($s['startsAt'], 11, 5) . ($s['version'] !== 'VF' ? ' ' . $s['version'] : '');
                $html .= $s['bookingUrl']
                    ? '<a href="' . esc_url($s['bookingUrl']) . '" rel="nofollow noopener" target="_blank">' . esc_html($label) . '</a> '
                    : '<span>' . esc_html($label) . '</span> ';
            }
            $html .= '</li>';
        }
        $html .= '</ul>';
    }
    return $html . '</div>';
}

Activez ensuite API Cinéma showtimes dans Extensions.

Comment ça marche

  • Une requête toutes les deux heures au plus. La réponse est gardée deux heures dans un transient : une page vue 10 000 fois par jour coûte toujours 12 requêtes par jour, 84 par semaine, dans les limites de l’offre gratuite.
  • to sans from. Sans from, l’API part de maintenant à l’heure locale du cinéma : les séances déjà commencées sont écartées ; to=2026-10-28 inclut toute cette journée.
  • include=movie. Le cinéma est le même sur chaque ligne : n’embarquer que le film allège la réponse.
  • Heures locales. startsAt est l’heure du cinéma (2026-10-24T20:30:00) : le plugin l’affiche telle quelle, quel que soit le fuseau du serveur.
  • Versions. La VF est la norme et n’est pas affichée ; VO et VOST s’ajoutent à côté de l’heure. Pour un cinéma américain, chaque horaire afficherait VO : remplacez le test par !in_array($s['version'], ['VF', 'VO'], true) pour la masquer.
  • Échappement. Titres et liens viennent des sites des cinémas : esc_html() et esc_url() les rendent inoffensifs.

L’utiliser

Dans une page, un article ou un bloc Code court :

[cinema_showtimes cinema="le-champo-paris-5e-arrondissement" days="3"]

days va de 1 à 14 (7 par défaut). Le résultat ressemble à ceci :

HTML
<div class="cinema-showtimes">
  <h3>jeudi 22 octobre</h3>
  <ul>
    <li><strong>Cris et Chuchotements</strong> <a href="…">11:50 VOST</a> <a href="…">21:50 VOST</a></li>
    <li><strong>Sonate d'automne</strong> <a href="…">13:40 VOST</a> …</li>
  </ul>
</div>

Les noms des jours suivent la langue du site, réglée dans Réglages › Général.

Un peu de style

Ajoutez dans Apparence › Personnaliser › CSS additionnel :

CSS
.cinema-showtimes ul { list-style: none; padding: 0; }
.cinema-showtimes li { margin: 0.4em 0; }
.cinema-showtimes a, .cinema-showtimes span {
  display: inline-block; margin: 0.15em 0.3em 0.15em 0; padding: 0.15em 0.5em;
  border: 1px solid currentColor; border-radius: 4px; text-decoration: none; font-variant-numeric: tabular-nums;
}

Pour aller plus loin

  • Plusieurs cinémas : le shortcode s’utilise autant de fois que voulu sur une page ; chaque cinéma a son propre cache.
  • Affiches : $s['movie']['posterUrl'] donne l’affiche du film, durationMin sa durée, synopsis son résumé.
  • Tous les cinémas d’une ville : appelez /v1/showtimes?city=… ou near=lat,lng au lieu d’un seul cinéma ; voir le guide pour la France.

Chaque champ est décrit dans la documentation.