API séances de cinéma

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

Champs de la réponse des séances :

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

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

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.

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

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

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 pour la fenêtre et les en-têtes, et tendances et listes 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

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.