Séances de cinéma

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.

curl -sf "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"

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);
  }
}

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
$url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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;
    }
}

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

• movie_idcheminobligatoire
  Identifiant numérique du film, par exemple 550.
• countryrequête
  Code pays à deux lettres comme RU. Sans lui, vous n'obtenez que le résumé par pays. region est un alias.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.

Champs de la réponse

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

{
  "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.

curl -sf "https://api.amodb.dev/3/movie/550/showtimes" \
  -H "Authorization: Bearer $AMODB_KEY"

{
  "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"
    }
  ]
}

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.

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.

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.

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 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.

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 et limites de débit.

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, et pour les autres données d'un film, voir films.