# API séances de cinéma > L'API de séances est GET /3/movie/{movie_id}/showtimes?country=US. Elle renvoie les cinémas avec adresse et fuseau horaire, et chaque séance avec heure de début, formats et lien de réservation quand ils sont connus. Sans country, seuls les totaux par pays reviennent. La couverture varie selon le titre, et un tableau results vide signifie que rien n'est connu. ## Obtenir les séances d'un film `GET /3/movie/{movie_id}/showtimes?country=US` renvoie les cinémas qui projettent un film dans un pays, chacun avec une liste de séances. `country` est un code à 2 lettres. Sans lui, `results` reste vide et vous n'obtenez que les totaux par pays. La couverture varie selon le pays et le titre, et un tableau `results` vide signifie que rien n'est connu pour ce couple. Vous obtenez le nom du cinéma, la chaîne, l'adresse et le fuseau horaire, et pour chaque séance l'heure de début, la salle, les formats, les étiquettes et un lien de réservation quand ils sont connus. Seules les séances à partir d'aujourd'hui sont renvoyées. La réponse décrit des séances. Ce n'est pas un service de billetterie. ## Les données obtenues | Point de terminaison | Renvoie | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `GET /3/movie/{movie_id}/showtimes` | Les cinémas et les séances d'un film dans `country`, ou des totaux par pays sans lui | | `GET /3/movie/now_playing` | Les films actuellement en salle, restreints par `region` | | `GET /3/movie/{movie_id}` avec `append_to_response=showtimes` | Les détails et les séances en une seule requête, voir [séances](https://amodb.dev/fr/showtimes/) | Champs de la réponse des séances : | Champ | Type | Signification | | ---------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- | | `id` | entier | Identifiant du film | | `country` | chaîne ou null | Le code à 2 lettres demandé, `null` si aucun n'était valide | | `results` | tableau | Un élément par cinéma, vide quand rien n'est connu ou que `country` manque | | `countries` | tableau | Totaux par pays : `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` | | `results[].id`, `name`, `city`, `address` | entier, chaînes | Identifiant, nom, ville et adresse postale du cinéma | | `results[].chain` | objet ou null | `key` et `name` de la chaîne de cinémas | | `results[].timezone` | chaîne ou null | Fuseau IANA du cinéma, par exemple `Europe/Moscow` | | `results[].latitude`, `longitude` | nombre ou null | Position, quand elle est connue | | `results[].region`, `postal_code`, `phone`, `url` | chaîne ou null | Autres détails du cinéma, souvent null | | `results[].showtimes` | tableau | Séances de ce cinéma | | `showtimes[].date` | chaîne | Jour local comme `2026-10-18` | | `showtimes[].start` | chaîne | Heure de début locale comme `2026-10-18T21:40`, sans décalage | | `showtimes[].auditorium` | chaîne ou null | Nom ou numéro de la salle | | `showtimes[].formats` | tableau | Formats de projection, par exemple `2D`, `IMAX` ou `Dolby Atmos` | | `showtimes[].tags` | tableau | Étiquettes supplémentaires comme `Reserved Seating` | | `showtimes[].booking_url` | chaîne ou null | Lien pour acheter un billet, quand il est connu | | `showtimes[].sold_out` | booléen | `true` quand la source marque la séance comme complète | | `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | divers, souvent null | Renseignés seulement quand la source du cinéma les fournit | Une réponse contient au plus 1 500 séances, triées par cinéma puis par heure de début. ## Démarrer en 3 étapes 1. Ouvrez les [tarifs](https://amodb.dev/fr/pricing/) et choisissez une offre. Les séances sont incluses dans toutes les offres. 2. Créez une clé dans le tableau de bord de votre compte. 3. Demandez `/3/movie/{movie_id}/showtimes` avec un code `country`, et passez la clé dans `api_key` ou dans un en-tête Bearer. ## Exemple de requête L'exemple bash lit les séances de Fight Club (id `550`) en Russie, où amodb a des séances aujourd'hui. L'exemple JS prend les cinq premiers films de la liste `now_playing` russe et affiche jusqu'à trois séances par cinéma, ou une note quand aucune n'est connue. ```bash curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const BASE = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path, params = {}) { const res = await fetch(`${BASE}${path}?${new URLSearchParams(params)}`, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const country = 'RU'; const playing = await get('/movie/now_playing', { region: country, page: 1 }); for (const movie of playing.results.slice(0, 5)) { const { results } = await get(`/movie/${movie.id}/showtimes`, { country }); if (results.length === 0) { console.log(`${movie.title}: no showtimes known`); continue; } for (const cinema of results) { const times = cinema.showtimes .slice(0, 3) .map((s) => `${s.start.slice(5, 10)} ${s.start.slice(11, 16)} ${s.formats.join('/')}`) .join(', '); console.log(`${movie.title} at ${cinema.name}, ${cinema.city}: ${times}`); } } ``` Réponse abrégée pour `country=RU` : le premier cinéma avec 2 de ses séances. ```json { "id": 550, "country": "RU", "results": [ { "id": 1114, "name": "Мираж Синема НА БОЛЬШОМ", "chain": { "key": "mirage-ru", "name": "Мираж Синема" }, "city": "Санкт-Петербург", "region": null, "address": "Большой пр. П.С., д. 35А", "postal_code": null, "country": "RU", "timezone": "Europe/Moscow", "latitude": null, "longitude": null, "phone": null, "url": "https://www.mirage.ru/spb/cinema/1/", "showtimes": [ { "date": "2026-10-18", "start": "2026-10-18T21:40", "end": null, "auditorium": null, "formats": [ "2D" ], "tags": [], "audio": null, "subtitles": null, "language": null, "price": null, "currency": null, "prices": null, "booking_url": "https://www.mirage.ru/ticket_new/aca7b114-d587-4fc5-9df6-28568e8fa9b3/", "sold_out": false }, { "date": "2026-10-19", "start": "2026-10-19T22:20", "end": null, "auditorium": "Зал №4", "formats": [ "2D" ], "tags": [], "audio": null, "subtitles": null, "language": null, "price": null, "currency": null, "prices": null, "booking_url": "https://www.mirage.ru/ticket_new/0c32e190-890a-4c81-a754-3300fefc4d5e/", "sold_out": false } ] } ], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 7, "first_day": "2026-10-18", "last_day": "2026-10-21" } ] } ``` ## Couverture et résultats vides Les données de cinéma ne sont pas disponibles pour chaque pays ni pour chaque titre. Concevez votre interface en conséquence. | Situation | Ce que vous voyez | Que faire | | -------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------- | | Séances connues | `results` a un élément par cinéma | Afficher la liste | | Rien de connu pour ce pays et ce titre | `results` est un tableau vide, `countries` liste les pays où des données existent | Afficher une note neutre, pas un tableau vide | | Aucun `country` envoyé | `results` est vide, `country` vaut `null`, `countries` contient des totaux | Laisser l'utilisateur choisir dans `countries` | | Identifiant de film inconnu | 404 avec `status_code` 34 | Vérifier l'identifiant | | Débit dépassé | 429 avec `status_code` 25 | Attendre les secondes de `Retry-After` | Un tableau vide n'est pas une erreur et ne prétend pas que le film est absent des cinémas. Il signifie qu'aucune donnée de séance n'est connue. Voir [erreurs](https://amodb.dev/fr/errors/) pour le format complet du corps. ## Construire une page de programmation des sorties actuelles Combinez deux points de terminaison. La liste indique quels films sont à l'affiche, et les séances remplissent les projections. | Étape | Requête | Remarques | | ----- | ---------------------------------------------- | ---------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | Jusqu'à 20 films par page, en cache 30 minutes | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | Un appel par film, en cache 30 minutes | | 3 | Filtrer dans votre code | Par `city`, `formats` ou `tags` | Une page de 20 films coûte 21 requêtes. La réponse d'une grosse sortie peut peser plusieurs centaines de kilo-octets, car elle contient jusqu'à 1 500 séances. Avec l'offre à 20 requêtes par minute, c'est une minute de budget entière : récupérez donc les données dans une tâche d'arrière-plan et servez les visiteurs depuis votre copie stockée. Les offres à 40 et 120 requêtes par minute conviennent à la même tâche avec de la marge. Voir [limites de débit](https://amodb.dev/fr/rate-limits/) pour la fenêtre et les en-têtes, et [tendances et listes](https://amodb.dev/fr/trending-lists/) pour les autres points de terminaison de listes. ## Garder votre copie à jour Les séances changent d'un jour à l'autre, contrairement aux détails d'un film. Stockez chaque réponse avec l'identifiant du film, le pays et l'heure de récupération. Une durée de vie de 30 minutes à quelques heures convient à la plupart des pages de programmation, et les séances déjà commencées peuvent être masquées en comparant `start` à l'heure actuelle dans le `timezone` du cinéma. Comme `start` n'a pas de décalage, ne le décalez pas dans le fuseau horaire du visiteur. ## Comparaison | Capacité | Extraire les sites des cinémas | API de métadonnées sans séances | amodb | | -------------------------------- | ---------------------------------- | ------------------------------- | -------------------------------------------------------------------- | | Mise en place | Un extracteur par site de cinéma | Non disponible | Un point de terminaison, une forme JSON | | Lien avec un identifiant de film | Associer par texte du titre | Non disponible | Identifiant du film dans le chemin | | Couverture | Ce que vous pouvez extraire | Aucune | Variable selon le pays et le titre, tableau vide quand c'est inconnu | | Formats et réservation | Analyser des libellés et des liens | Non disponible | Champs `formats`, `tags` et `booking_url` | | Entretien | Casse quand un site change | Aucun | Une seule forme JSON pour tous les pays | ## Tarifs Les offres prépayées durent 1, 3, 6, 12 ou 24 mois, avec 0, 10, 20, 30 ou 40 pour cent de réduction pour les plus longues. Rien ne se renouvelle automatiquement. Les offres autorisent 20, 40 et 120 requêtes par minute et chacune inclut les séances avec toutes les autres données. Une page de programmation actualisée toutes les 30 minutes pour quelques pays tient dans le plus petit débit. Il n'y a pas d'offre gratuite. Choisissez une offre sur les [tarifs](https://amodb.dev/fr/pricing/). ## Questions et réponses ### Comment obtenir les séances d'un film ? Envoyez GET /3/movie/{movie_id}/showtimes?country=US avec votre clé. Le paramètre country est un code à 2 lettres, et region fonctionne comme alias. La réponse liste les cinémas, et chaque cinéma contient ses séances avec heure de début, formats, étiquettes et lien de réservation quand ils sont connus. ### Que signifie un tableau results vide ? Cela signifie qu'amodb n'a aucune donnée de séance pour ce film dans ce pays. Ce n'est pas une erreur, et cela ne dit pas que le film est absent des cinémas. Le tableau countries de la même réponse liste quand même les pays où des données existent, ce qui permet de proposer un autre pays. ### Quels pays sont couverts ? La couverture varie selon le pays et le titre. Chaque réponse contient un tableau countries avec les nombres de salles, de villes et de séances, jusqu'à 60 pays, ceux qui ont le plus de séances en premier. Lisez-le pour chaque film au lieu d'écrire une liste en dur. ### Puis-je lister les films actuellement en salle ? Oui. GET /3/movie/now_playing avec le paramètre region liste les sorties en cours, mises en cache 30 minutes. Prenez l'identifiant de chaque film de cette liste et demandez ses séances avec le même code pays. ### Quel fuseau horaire utilisent les valeurs start ? Une valeur start ressemble à 2026-10-18T21:40 et ne porte aucun décalage UTC. Considérez-la comme l'heure locale affichée au cinéma. Chaque salle a aussi un timezone comme Europe/Moscow. Ne convertissez pas start dans le fuseau horaire du visiteur. ## Pages liées - [Séances de cinéma](https://amodb.dev/fr/showtimes/): API de séances qui renvoie salles et horaires d'un film dans un pays, ou un résumé par pays. À fusionner aux détails ou à associer à now_playing. - [Tendances et points de terminaison de listes](https://amodb.dev/fr/trending-lists/): API de tendances aux chemins TMDB v3 : classements jour et semaine, plus films et séries à l'affiche, populaires, mieux notés et à venir, cache de 30 minutes. - [API de détails de film](https://amodb.dev/fr/movies/): API de détails de film aux chemins et au JSON de TMDB v3. Obtenez un film par id, ajoutez crédits, notes et ambiances avec append_to_response, en 14 langues. - [Limites de débit](https://amodb.dev/fr/rate-limits/): amodb limite chaque clé en requêtes par minute sur une fenêtre glissante de 60 secondes : 20, 40 ou 120 selon l'offre. Lisez les en-têtes et gérez le 429. - [Démarrage rapide](https://amodb.dev/fr/quickstart/): Faites votre premier appel amodb : obtenez une clé, demandez un film en curl, JavaScript, Python, PHP ou Go, puis chargez l'affiche. En moins de 2 minutes. Mis à jour: 2026-10-18. Source: https://amodb.dev/fr/cinema-showtimes-api/