# Séances de cinéma > GET /3/movie/{movie_id}/showtimes?country=RU renvoie les salles qui projettent un film dans un pays, avec leurs séances datées. Sans country, il ne renvoie que des totaux par pays dans une liste countries. La couverture varie selon le pays et le titre, et un tableau results vide signifie que rien n'est connu pour ce couple. ## Point de terminaison `GET /3/movie/{movie_id}/showtimes` ```bash curl "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` Réponse: ```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-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 }, { "date": "2026-10-20", "start": "2026-10-20T21: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/7f18e423-4a40-40f3-b68f-8664f4e3fa75/", "sold_out": false }, { "date": "2026-10-21", "start": "2026-10-21T21: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/5ad6b82b-82b3-4ea6-9e65-79388d71b230/", "sold_out": false } ] }, { "id": 1115, "name": "Мираж Синема ПИК", "chain": { "key": "mirage-ru", "name": "Мираж Синема" }, "city": "Санкт-Петербург", "region": null, "address": "ул. Ефимова, д.2", "postal_code": null, "country": "RU", "timezone": "Europe/Moscow", "latitude": null, "longitude": null, "phone": null, "url": "https://www.mirage.ru/spb/cinema/27/", "showtimes": [ { "date": "2026-10-19", "start": "2026-10-19T20:10", "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/1d143ca6-1bbe-48ee-954a-063b6088a32a/", "sold_out": false }, { "date": "2026-10-20", "start": "2026-10-20T20:10", "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/8b2e0f6a-5b62-41eb-a398-1b709539f03d/", "sold_out": false }, { "date": "2026-10-21", "start": "2026-10-21T20:10", "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/3723875b-a7df-426f-968a-4bdaa1a8bdd7/", "sold_out": false } ] } ], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 6, "first_day": "2026-10-19", "last_day": "2026-10-21" } ] } ``` ## Obtenir les séances d'un film `GET /3/movie/{movie_id}/showtimes?country=RU` renvoie les salles qui projettent un film dans un pays, avec les séances datées de chacune. Le paramètre `country` accepte un code à deux lettres, en majuscules ou en minuscules. La couverture varie selon le pays et le titre : les données sont présentes là où elles sont connues et manquent là où elles ne le sont pas. Seuls les jours à partir d'aujourd'hui sont renvoyés. L'exemple demande Fight Club en Russie et gère une réponse vide. ```bash curl -sf "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const data = await res.json(); if (data.results.length === 0) console.log('no showtimes known'); for (const venue of data.results) { for (const s of venue.showtimes) { console.log(venue.name, venue.city, s.start, s.formats.join(','), s.booking_url); } } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/550/showtimes", params={"country": "RU"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() results = r.json()["results"] if not results: print("no showtimes known") for venue in results: for s in venue["showtimes"]: print(venue["name"], venue["city"], s["start"], ",".join(s["formats"])) ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $results = json_decode($body, true)['results']; if (!$results) { echo 'no showtimes known', PHP_EOL; } foreach ($results as $venue) { foreach ($venue['showtimes'] as $s) { echo $venue['name'], ' ', $s['start'], ' ', implode(',', $s['formats']), PHP_EOL; } } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "strings" "time" ) type Venue struct { Name string `json:"name"` City string `json:"city"` Showtimes []struct { Start string `json:"start"` Formats []string `json:"formats"` BookingURL string `json:"booking_url"` } `json:"showtimes"` } func main() { url := "https://api.amodb.dev/3/movie/550/showtimes?country=RU" req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var body struct { Results []Venue `json:"results"` } if err := json.NewDecoder(res.Body).Decode(&body); err != nil { panic(err) } if len(body.Results) == 0 { fmt.Println("no showtimes known") } for _, v := range body.Results { for _, s := range v.Showtimes { fmt.Println(v.Name, v.City, s.Start, strings.Join(s.Formats, ",")) } } } ``` ### Paramètres | Paramètre | Dans | Requis | Description | | ---------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------------ | | `movie_id` | chemin | oui | Identifiant numérique du film, par exemple `550`. | | `country` | requête | non | Code pays à deux lettres comme `RU`. Sans lui, vous n'obtenez que le résumé par pays. `region` est un alias. | | `api_key` | requête | l'un des deux | Votre clé. Utilisez-la ou l'en-tête `Authorization: Bearer`. | ### Champs de la réponse | Champ | Type | Remarques | | ------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `id` | entier | Identifiant du film. | | `country` | chaîne ou null | Le code en majuscules demandé, ou `null` quand `country` manque ou n'a pas deux lettres. | | `results` | tableau | Un objet par salle, triées par salle. Vide quand rien n'est connu ou qu'aucun pays n'a été envoyé. Au plus 1500 séances en tout. | | `results[].id` | entier | Identifiant de la salle. | | `results[].name` | chaîne | Nom de la salle. | | `results[].chain` | objet | `key` est la clé de la chaîne, `name` est le nom de la chaîne ou `null`. | | `results[].city` | chaîne ou null | Ville. | | `results[].region` | chaîne ou null | Région. | | `results[].address` | chaîne ou null | Adresse postale. | | `results[].postal_code` | chaîne ou null | Code postal. | | `results[].country` | chaîne | Code pays de la salle. | | `results[].timezone` | chaîne ou null | Fuseau horaire IANA comme `Europe/Moscow`. | | `results[].latitude`, `results[].longitude` | nombre ou null | Position de la salle. | | `results[].phone` | chaîne ou null | Numéro de téléphone. | | `results[].url` | chaîne ou null | Page de la salle. | | `results[].showtimes` | tableau | Séances dans cette salle, triées par début. | | `results[].showtimes[].date` | chaîne | Jour sous la forme `2026-10-18`. | | `results[].showtimes[].start` | chaîne | Début en heure locale de la salle comme `2026-10-18T21:40`, sans décalage UTC. | | `results[].showtimes[].end` | chaîne ou null | Fin en heure locale de la salle. | | `results[].showtimes[].auditorium` | chaîne ou null | Nom de la salle de projection. | | `results[].showtimes[].formats` | tableau de chaînes | Formats comme `2D`. | | `results[].showtimes[].tags` | tableau de chaînes | Étiquettes supplémentaires. Souvent vide. | | `results[].showtimes[].audio`, `subtitles`, `language` | chaîne ou null | Détails d'audio, de sous-titres et de langue quand ils sont connus. | | `results[].showtimes[].price` | nombre ou null | Prix du billet. | | `results[].showtimes[].currency` | chaîne ou null | Devise de `price`. | | `results[].showtimes[].prices` | n'importe quoi ou null | Détails de prix quand une salle en a plusieurs. | | `results[].showtimes[].booking_url` | chaîne ou null | Lien pour réserver la place. | | `results[].showtimes[].sold_out` | booléen | `true` quand la séance est complète. | | `countries` | tableau | Résumé par pays, voir ci-dessous. | Lisez par leur nom les clés que vous utilisez et ignorez les clés supplémentaires dans un objet de salle ou de séance. Beaucoup de champs valent `null` aujourd'hui, car toutes les salles ne les envoient pas. ### Exemple de réponse ```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" } ] } ``` La liste est réduite à 1 salle sur 2 et à 2 séances sur 4. Les séances n'existent que pour les jours qui ne sont pas passés : cette réponse change donc chaque jour. ## Obtenir le résumé par pays Omettez `country` et la réponse ne contient que des totaux. `results` reste vide et `country` vaut `null`. Le tableau `countries` liste jusqu'à 60 pays qui ont encore une séance, celui qui a le plus de séances en premier. Utilisez-le pour savoir où un titre est à l'affiche avant de demander les salles. ```bash curl -sf "https://api.amodb.dev/3/movie/550/showtimes" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```json { "id": 550, "country": null, "results": [], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 7, "first_day": "2026-10-18", "last_day": "2026-10-21" } ] } ``` | Champ | Type | Remarques | | ----------------------------------------------- | ------ | ---------------------------------------------------------- | | `countries[].country` | chaîne | Code à deux lettres, prêt à servir de paramètre `country`. | | `countries[].name` | chaîne | Nom du pays en anglais. | | `countries[].venues` | entier | Salles ayant une séance. | | `countries[].cities` | entier | Villes ayant une séance. | | `countries[].showtimes` | entier | Séances à partir d'aujourd'hui. | | `countries[].first_day`, `countries[].last_day` | chaîne | Premier et dernier jour ayant une séance. | Un code pays sans données, comme `country=US` pour ce film, répond `country` à `US`, un `results` vide et la même liste `countries`. Un titre sans aucune séance nulle part, comme la série 1396, a `"countries": []`. ## Ajouter les séances à un appel de détails `append_to_response=showtimes` fusionne le même bloc dans une réponse de détails sous la clé `showtimes`. Envoyez le code `country` dans la même requête. Le bloc garde ses propres clés `id`, `country`, `results` et `countries`. | Requête | Résultat | | -------------------------------------------------------------- | ----------------------------------------------------- | | `/3/movie/550?append_to_response=showtimes&country=RU` | Fiche du film plus un bloc `showtimes` pour la Russie | | `/3/movie/550?append_to_response=credits,showtimes&country=RU` | Ajoute les crédits au même appel | Cela compte pour une seule requête : une page de film qui montre la distribution et les séances n'a donc besoin que d'un appel. Le même point de terminaison existe pour les séries sous `GET /3/tv/{tv_id}/showtimes`. ## Combiner avec now_playing et region La liste des films à l'affiche vous donne les titres. Le point de terminaison des séances vous donne les projections d'un titre. Reliez-les dans votre code. | Étape | Requête | Résultat | | ----- | ------------------------------------------------------- | ---------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=RU&page=1` | Jusqu'à 20 films par page, en cache 30 minutes | | 2 | `GET /3/movie/{id}/showtimes?country=RU` pour chaque id | Salles et horaires, quand ils sont connus | La boucle ci-dessous réessaie une ou deux fois quand la limite de l'offre est atteinte, en attendant le nombre de secondes de `Retry-After`. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path, retries = 2) { const res = await fetch(base + path, { headers }); if (res.status === 429 && retries > 0) { const wait = Number(res.headers.get('Retry-After') ?? 60); await new Promise((resolve) => setTimeout(resolve, wait * 1000)); return get(path, retries - 1); } if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const playing = await get('/movie/now_playing?region=RU&page=1'); for (const movie of playing.results) { const data = await get(`/movie/${movie.id}/showtimes?country=RU`); if (data.results.length > 0) console.log(movie.title, data.results.length, 'venues'); } ``` Une page de 20 titres représente 20 requêtes de séances. Avec l'offre à 20 requêtes par minute, cela consomme toute la fenêtre : mettez donc le résultat en cache de votre côté. Voir [tendances et listes](https://amodb.dev/fr/trending-lists/) pour les paramètres de liste. ## Erreurs Le corps d'erreur suit TMDB : `success`, `status_code` et `status_message`. Une mauvaise clé donne `status_code` 7. | HTTP | status_code | Quand | | ---- | ----------- | ----------------------------------------------------------------------------- | | 401 | 7 | La clé est absente ou fausse. | | 402 | 36 | La période de l'offre est terminée. | | 404 | 34 | Aucun film avec cet identifiant. | | 429 | 25 | Au-dessus de vos requêtes par minute. Attendez les secondes de `Retry-After`. | Aucune séance n'est pas une erreur : attendez-vous à un statut 200 et à un tableau `results` vide. Un `country` absent ou invalide n'est pas une erreur non plus. Voir [erreurs](https://amodb.dev/fr/errors/) et [limites de débit](https://amodb.dev/fr/rate-limits/). ## Remarques pratiques - La couverture varie selon le pays et le titre. Traitez un tableau `results` vide comme inconnu, pas comme « ne passe pas ». - Affichez `start` exactement comme renvoyé. C'est l'heure locale de la salle sans décalage UTC, et l'horloge de la salle est ce qu'attendent les visiteurs. - Les séances sont mises en cache 30 minutes en périphérie. Ne les demandez pas à chaque vue de page, et gardez votre propre cache court. - Réutilisez une même liste de films à l'affiche pour tous les visiteurs d'une région. Elle est aussi mise en cache 30 minutes en périphérie. - Utilisez `booking_url` pour envoyer un visiteur vers la page de réservation de la salle. Il vaut `null` quand la salle ne donne aucun lien. - Pour l'aperçu du cas d'usage, voir l'[API de séances de cinéma](https://amodb.dev/fr/cinema-showtimes-api/), et pour les autres données d'un film, voir [films](https://amodb.dev/fr/movies/). ## Questions et réponses ### Le paramètre country est-il obligatoire ? Non, mais il vous le faut pour obtenir les salles. Envoyez un code à deux lettres comme RU ou DE. Sans country, ou avec un code qui n'a pas deux lettres, results est vide et la liste countries montre où des séances existent. Le paramètre region fonctionne comme alias. ### Que signifie un tableau results vide ? Cela signifie qu'aucune séance n'est connue pour ce titre dans ce pays à partir d'aujourd'hui. Cela ne prouve pas que le film n'est pas à l'affiche. La liste countries montre quand même d'autres pays qui ont des données. Proposez plutôt la date de sortie tirée des détails du film. ### Comment trouver les films actuellement en salle ? Appelez GET /3/movie/now_playing avec le paramètre region, puis demandez les séances des identifiants qui vous intéressent. La liste est mise en cache 30 minutes : vous pouvez donc la réutiliser pour chaque visiteur. ### Les heures sont-elles dans le fuseau horaire de mon visiteur ? Non. La valeur start est l'heure locale de la salle et n'a pas de décalage UTC. Chaque salle a aussi un timezone comme Europe/Moscow. Affichez start tel que renvoyé et ne le convertissez pas avec le fuseau horaire du visiteur. ## Pages liées - [API séances de cinéma](https://amodb.dev/fr/cinema-showtimes-api/): API séances de cinéma : GET /3/movie/{movie_id}/showtimes avec un code pays renvoie cinémas, horaires et formats si connus. À 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. - [Notes des films et séries](https://amodb.dev/fr/ratings/): API de notes de films : scores IMDb, Kinopoisk, Metacritic, Rotten Tomatoes et TMDB d'un titre en un appel, avec null pour toute source inconnue. - [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/showtimes/