API des séances de cinéma

Les séances de cinéma en France et aux États-Unis (filtre country). Authentification par clé d’API (Authorization: Bearer ac_live_…), créée depuis le tableau de bord. Les heures sont des heures locales, dans le fuseau de chaque cinéma (cinema.timezone).

Titres, synopsis, genres et identifiants TMDB des films viennent de TMDB une fois le film rapproché (tmdbId renseigné) ; rawTitle garde le titre tel que publié par le cinéma. Ce produit utilise l’API TMDB mais n’est ni approuvé ni certifié par TMDB.

L’usage de l’API est soumis aux conditions d’utilisation : un compte par client, clés d’API gardées côté serveur, pas de revente ni de redistribution en masse des données, pas de contournement des quotas.

Exemples

Chaque appel demande votre clé d’API. Les listes sont paginées (limit, cursor), et sans date ni from les séances partent de maintenant, à l’heure locale de chaque cinéma.

Toutes les séances d’un film en France, à partir de son identifiant Allociné ou TMDB

L’identifiant Allociné est le nombre dans l’URL de la fiche du film (allocine.fr/film/fichefilm_gen_cfilm=1000013045.html pour L’Odyssée) ; l’identifiant TMDB est celui de themoviedb.org/movie/1368337. Inutile de connaître notre identifiant de film :

curl "https://api.api-cinema.com/v1/showtimes?allocine_id=1000013045&country=FR&limit=100" -H "Authorization: Bearer ac_live_…"
curl "https://api.api-cinema.com/v1/showtimes?tmdb_id=1368337&country=FR&limit=100" -H "Authorization: Bearer ac_live_…"

Pour obtenir nos identifiants de film (pour /v1/movies/{id}), cherchez le film avec les mêmes identifiants :

curl "https://api.api-cinema.com/v1/movies?allocine_id=1000013045" -H "Authorization: Bearer ac_live_…"
# → deux lignes, une par pays, même tmdbId 1368337 :
#   { "id": "065ec55d-…", "title": "L'Odyssée", "allocineId": "1000013045", "tmdbId": 1368337 }
#   { "id": "e125e88f-…", "title": "The Odyssey", "allocineId": null, "tmdbId": 1368337 }

Toutes les séances d’un film, à partir de son nom

Pas d’identifiant Allociné ou TMDB sous la main ? Cherchez d’abord le film par son nom, puis lisez ses séances :

# 1. trouver le film parmi ceux à l’affiche en France
curl "https://api.api-cinema.com/v1/movies?q=spider&playing=true&country=FR" -H "Authorization: Bearer ac_live_…"
# → { "id": "a1…", "title": "Spider-Man : Brand New Day", "rawTitle": "SPIDER-MAN : BRAND NEW DAY", "tmdbId": 969681 }
#   { "id": "b2…", "title": "Spider-Man : Brand New Day", "rawTitle": "SPIDERMAN", "tmdbId": 969681 }
#   { "id": "c3…", "title": "Spider-Man : New Generation", "rawTitle": "Spider-Man : New Generation", "tmdbId": 324857 }

# 2. choisir le film, puis toutes ses séances (les deux premières lignes) par son tmdbId
curl "https://api.api-cinema.com/v1/showtimes?tmdb_id=969681&country=FR&limit=100" -H "Authorization: Bearer ac_live_…"

Si le film choisi n’a pas encore de tmdbId (titleSource: "raw"), lisez plutôt les séances de chaque ligne avec GET /v1/movies/{id}/showtimes.

Comment marche la recherche dans le titre (q)

• Votre texte et les titres sont comparés après la même normalisation : minuscules, accents et ponctuation retirés, article initial supprimé (le, la, les, l', un, une, des, the, a, an). L'Odyssée, l odyssee et ODYSSEE sont la même recherche.
• C’est une recherche contient sur le titre tel que publié par le cinéma (rawTitle), pas sur le titre TMDB ni le titre original : en France, q=odyssee trouve L’Odyssée mais q=the odyssey ne trouve rien (les lignes américaines portent le titre anglais).
• Les cinémas écrivent les titres à leur façon (SPIDERMAN, SPIDER-MAN : BRAND NEW DAY) : cherchez un mot court et distinctif (spider) plutôt que le titre complet.
• Plusieurs films peuvent correspondre (q=odyssee renvoie aussi 2001 : L’Odyssée de l’espace), et un même film peut arriver en plusieurs lignes (une par titre publié ou par pays) : choisissez selon title, year ou tmdbId, jamais aveuglément le premier résultat, puis continuez avec tmdb_id.
• Ajoutez playing=true pour ne garder que les films avec des séances à venir, et country pour rester dans un pays. Les résultats sont triés par titre et paginés (limit, offset).

Ce qui passe à New York

city compare exactement le nom de la ville (« New York » exclut « Brooklyn ») : cherchez plutôt autour d’un point. Times Square, 5 km :

curl "https://api.api-cinema.com/v1/showtimes?country=US&near=40.758,-73.9855&radius_km=5&limit=200" -H "Authorization: Bearer ac_live_…"

Ajoutez date=2026-09-25 pour une seule journée ; chaque séance porte cinema.distanceKm. Les cinémas eux-mêmes, du plus proche au plus lointain :

curl "https://api.api-cinema.com/v1/cinemas?country=US&near=40.758,-73.9855&radius_km=5" -H "Authorization: Bearer ac_live_…"

Ce soir près de chez moi, en VOST

La même recherche avec un corps JSON (POST …/search), plus simple à construire depuis du code :

const res = await fetch('https://api.api-cinema.com/v1/showtimes/search', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ac_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    near: { lat: 45.764, lng: 4.8357, radiusKm: 3 }, // centre de Lyon
    from: '2026-09-25T18:00', // ce soir, à l’heure locale de chaque cinéma
    to: '2026-09-25T23:59',
    version: 'VOST',
    include: ['movie', 'cinema'],
    limit: 100,
  }),
})
const { data } = await res.json()
for (const s of data)
  console.log(s.startsAt.slice(11, 16), s.movie.title, '—', s.cinema.name, `${s.cinema.distanceKm} km`)

Le programme d’un cinéma pour la semaine

Trouvez le cinéma par son nom, puis lisez ses séances (le chemin accepte son id ou son slug) :

curl "https://api.api-cinema.com/v1/cinemas?q=champo&country=FR" -H "Authorization: Bearer ac_live_…"
# → { "id": "cnc_8422", "slug": "le-champo-paris-5e-arrondissement", "name": "Le Champo", … }
curl "https://api.api-cinema.com/v1/cinemas/le-champo-paris-5e-arrondissement/showtimes?from=2026-09-24&to=2026-09-30" -H "Authorization: Bearer ac_live_…"

Sans from / to, les séances d’un cinéma sont celles du jour. Les séances passées sont gardées 7 jours.

Pour choisir parmi les cinémas d’un code postal (ou d’un ZIP code aux États-Unis), passez zip_code ; ses premiers chiffres suffisent, zip_code=69 liste tout un département :

curl "https://api.api-cinema.com/v1/cinemas?zip_code=75005" -H "Authorization: Bearer ac_live_…"

Les films à l’affiche dans un pays

curl "https://api.api-cinema.com/v1/movies?playing=true&country=FR&limit=100" -H "Authorization: Bearer ac_live_…"
curl "https://api.api-cinema.com/v1/movies?q=odyssey&playing=true&country=US" -H "Authorization: Bearer ac_live_…"

Regroupez les films par tmdbId : un même film a un id par pays, et un par titre publié tant qu’il n’est pas rapproché sur TMDB.

Tenir une copie locale à jour

Importez tout une fois, puis ne récupérez que les changements avec updated_since : voir Synchronisation incrémentale plus bas.

Nouveautés

2026-10-30 — Chercher des cinémas par code postal / ZIP code

Nouveau filtre sur /v1/cinemas : zip_code (zipCode dans le corps de POST /v1/cinemas/search, et sur l’outil MCP search_cinemas). Il garde les cinémas dont le postalCode commence par les chiffres donnés, de 2 à 5 : zip_code=75005 pour un code, zip_code=75 pour tout un département français, zip_code=100 pour une plage de ZIP codes américains. Il se combine avec les autres filtres. Les cinémas sans postalCode connu sont exclus.

Ce qu’il faut faire si vous utilisez déjà l’API

• Rien à faire. Si vous convertissiez un code postal en ville ou en point pour chercher, vous pouvez le passer directement.

2026-10-29 — Un compte par client : 403 account_suspended

Quand un compte est créé depuis une connexion qui en a déjà un, son accès à l’API est suspendu : toute requête répond 403 avec le code account_suspended, et le compte reçoit un e-mail. Les conditions d’utilisation autorisent un seul compte par client (article 2) ; le compte créé en premier n’est pas concerné.

Ce qu’il faut faire si vous utilisez déjà l’API

• Rien à faire avec un seul compte. Si plusieurs personnes ou sociétés partagent une même connexion (un bureau partagé, par exemple), écrivez à support@api-cinema.com.

2026-10-22 — Forfait gratuit : 150 requêtes par semaine, usage non commercial

Le forfait Gratuit passe à 150 requêtes par semaine (au lieu de 250), toutes ses clés d’API confondues, et est réservé aux tests et aux projets non commerciaux (conditions d’utilisation, article 4). Un site ou une application qui génère des revenus ou sert une entreprise, y compris le site d’un cinéma, nécessite un forfait payant (Starter, 12 € par mois, 10 000 requêtes par semaine). Les forfaits payants et les comptes sur devis ne changent pas.

Ce qu’il faut faire si vous utilisez déjà l’API

• Si vous êtes sur le forfait Gratuit, vérifiez votre consommation hebdomadaire dans le tableau de bord : au-delà de 150 requêtes, l’API répond 429 avec weekly_quota_exceeded jusqu’au lundi 00:00 UTC.
• Si votre usage est commercial, passez à un forfait payant depuis le tableau de bord.

2026-10-22 — city=Paris trouve tous les arrondissements

Les cinémas parisiens sont classés par arrondissement ("city": "Paris 5e Arrondissement"), donc city=Paris ne renvoyait rien. Le filtre couvre désormais Paris et tous ses arrondissements, sur /v1/cinemas, /v1/showtimes et leurs variantes search ; un arrondissement seul (city=Paris 5e Arrondissement) marche toujours. Les autres villes gardent une comparaison exacte.

Ce qu’il faut faire si vous utilisez déjà l’API

• Si vous contourniez le problème en listant les arrondissements ou en cherchant autour d’un point, vous pouvez passer à city=Paris.

2026-10-19 — Une semaine de séances passées

Les séances passées sont désormais gardées 7 jours : un date ou un from antérieur à une semaine ne renvoie rien pour les jours d’avant. Les séances à venir et la synchronisation updated_since ne changent pas ; les séances passées disparaissent simplement après une semaine, sans entrée de retrait.

Ce qu’il faut faire si vous utilisez déjà l’API

• Si vous avez besoin d’un historique plus long, enregistrez les séances de votre côté au fil de vos imports.

2026-09-27 — Réponses plus rapides, nouvelle base de données

L’API tourne maintenant sur une nouvelle base de données. Les requêtes lourdes sont bien plus rapides (films à l’affiche dans un pays, toutes les séances d’un film : de 2 à 7 fois), les autres aussi rapides ou plus. Les réponses ne changent pas, avec deux petites améliorations : la recherche q ignore désormais aussi la casse des lettres accentuées (un nom accentué en majuscules trouve son écriture en minuscules), et les films de même titre sont toujours listés dans le même ordre. Une clé d’API révoquée est maintenant refusée dans la minute plutôt qu’immédiatement.

2026-09-24 — Conditions d’utilisation

L’API a désormais des conditions d’utilisation publiées, en lien en haut de cette page et dans info.termsOfService de l’OpenAPI. Elles formalisent ce qui était déjà attendu : un compte par client, des clés d’API gardées côté serveur et jamais partagées, pas de revente ni de redistribution en masse des données, et pas de contournement des quotas par des clés ou des comptes supplémentaires.

Ce qu’il faut faire si vous utilisez déjà l’API

• Vérifiez que vos clés d’API ne servent que côté serveur (jamais dans une page web ou une application mobile).
• Si vous avez besoin de plus de volume, demandez au support plutôt que d’ajouter des clés ou des comptes.

2026-09-24 — Quota hebdomadaire par compte

Un compte peut maintenant avoir un quota de requêtes hebdomadaire (lundi 00:00 UTC → dimanche, toutes ses clés d’API confondues). S’il en a un, les réponses portent X-Weekly-Quota-Limit, X-Weekly-Quota-Remaining et X-Weekly-Quota-Reset, et au-delà du quota l’API répond 429 avec le code weekly_quota_exceeded. Rien ne change pour les comptes sans quota hebdomadaire.

Ce qu’il faut faire si vous utilisez déjà l’API

• Si vous gérez les réponses 429, attendez-vous aussi au code weekly_quota_exceeded : son Retry-After peut durer plusieurs jours.

2026-09-23 — Recherche JSON (POST)

Chaque liste avec filtres a désormais une jumelle POST …/search qui prend ses filtres dans un corps JSON, avec des valeurs typées et des noms en camelCase (tmdbId, near: { lat, lng, radiusKm }, include: ["movie"]…) : plus de longues URL à construire. Même réponse, même pagination (cursor), même quota ; les clés inconnues sont refusées (400).

2026-09-23 — Séances par identifiant TMDB ou Allociné

/v1/showtimes et /v1/movies acceptent tmdb_id et allocine_id (l’identifiant de allocine.fr/film/fichefilm_gen_cfilm=<id>.html) : toutes les séances d’un film, quel que soit le titre publié par chaque cinéma. allocine_id trouve aussi les séances lues sur d’autres sources une fois le film rapproché sur TMDB. Les films exposent un nouveau champ allocineId (renseigné quand le film a été lu sur Allociné).

2026-09-23 — Cinémas aux États-Unis

L’API couvre désormais les cinémas des États-Unis en plus de la France. Sans paramètre country, les listes renvoient les deux pays : /v1/cinemas, /v1/showtimes, /v1/movies et /v1/movies/{id}/showtimes incluent les cinémas et séances américains.

• Nouveau filtre country (FR ou US) sur ces quatre listes, et dans les outils MCP.
• Nouveaux champs de cinéma : country et timezone (zone IANA, par exemple America/New_York). Aux États-Unis, region contient le code de l’État (NY) et postalCode le ZIP code.
• startsAt reste une heure locale sans décalage, mais c’est désormais l’heure locale du cinéma (cinema.timezone), et plus toujours Europe/Paris.
• Sans date ni from, « maintenant » et « aujourd’hui » sont évalués dans le fuseau de chaque cinéma. date, from et to se lisent à l’heure locale de chaque cinéma.
• Hors de France, cncId, inseeCode, department et artEtEssai valent null.
• Séances américaines : version vaut VO (version originale) ou VOST (sous-titrée), UNKNOWN pour une séance doublée.
• Les films des cinémas américains ont leurs propres lignes, séparées des françaises, avec titre, synopsis et genres TMDB en anglais. Un film projeté dans les deux pays a donc un id par pays et le même tmdbId.

Ce qu’il faut faire si vous utilisez déjà l’API

• Pour garder exactement votre périmètre actuel, ajoutez country=FR à vos appels de listes (cinémas, séances, films, séances d’un film). Les appels par id (/v1/cinemas/{id}, /v1/movies/{id}) ne changent pas.
• Pour convertir startsAt en instant (UTC, affichage dans un autre fuseau), utilisez cinema.timezone au lieu de supposer Europe/Paris.
• Si votre code lit cncId, inseeCode, department ou artEtEssai, acceptez null pour les cinémas hors de France.
• Si vous regroupez les films, utilisez tmdbId plutôt que id ou le titre (un id par pays).
• Si vous validez country ou timezone avec un schéma strict, ajoutez ces deux champs.

Versions

L’URL porte la version majeure (/v1/…) ; le sélecteur en haut de la référence interactive montre la documentation de chaque version, la plus récente par défaut.

• Les ajouts (nouvelles routes, nouveaux paramètres facultatifs, nouveaux champs de réponse) arrivent dans toutes les versions maintenues sans changement de version : ignorez les champs que vous ne connaissez pas.
• Un changement incompatible (autre comportement par défaut, champ supprimé ou renommé, validation plus stricte) ouvre une nouvelle version majeure ; votre version actuelle ne change pas.
• Une version remplacée reste servie au moins 6 mois. Ses réponses portent alors les en-têtes Deprecation, Sunset (dernier jour de service) et Link: <…>; rel="successor-version".

Import complet des séances

• Parcourez GET /v1/showtimes avec limit=1000 et cursor (le meta.nextCursor de la page précédente).
• include choisit les objets embarqués : movie,cinema par défaut, include=movie ou include= (vide) pour des pages bien plus légères. movieId et cinemaId sont toujours là : chargez films et cinémas une fois, à part.
• Regroupez un film par movie.tmdbId : deux cinémas publiant des titres différents donnent deux movie.id pour le même tmdbId. movie.titleSource vaut tmdb ou raw ; GET /v1/movies/unmatched liste les films à l’affiche encore sans tmdbId.
• cinema.programmeCheckedAt est la dernière lecture réussie du programme du cinéma : au-delà de 2 jours, il peut être dépassé.
• showtime.id est stable : une séance garde son id tant que son cinéma, son film, son heure et sa version ne changent pas.

Recherche JSON

Plutôt qu’une longue URL, envoyez les filtres dans un corps JSON (noms en camelCase, valeurs typées) : chaque liste a sa jumelle POST …/search (/v1/showtimes/search, /v1/cinemas/search, /v1/movies/search, /v1/cinemas/{id}/showtimes/search, /v1/movies/{id}/showtimes/search). Réponse, pagination et quota sont les mêmes qu’avec GET.

const res = await fetch('https://api.api-cinema.com/v1/showtimes/search', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ac_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    country: 'FR',
    allocineId: '1000013045',
    near: { lat: 45.764, lng: 4.8357, radiusKm: 5 },
    from: '2026-09-25T18:00',
    to: '2026-09-26',
    version: 'VOST',
    include: ['movie'],
    limit: 100,
  }),
})
const { data, meta } = await res.json() // page suivante : même corps + cursor: meta.nextCursor

Synchronisation incrémentale

1. Import complet : parcourez GET /v1/showtimes et gardez le meta.syncedAt de la première page.
2. Ensuite : GET /v1/showtimes?updated_since=<syncedAt> (mêmes filtres from/to…) ne renvoie que les séances ajoutées, modifiées ou retirées depuis, triées par updatedAt, avec le même cursor. Gardez à nouveau le meta.syncedAt de sa première page.
3. Une séance avec removedAt renseigné n’est plus publiée par le cinéma (annulée ou retirée) : supprimez-la de votre côté. Les listes normales ne renvoient jamais une séance retirée.
4. GET /v1/movies?updated_since=… donne les films modifiés (rapprochement TMDB, titre, synopsis).

syncedAt est pris quelques minutes avant la requête : une séance peut arriver deux fois, appliquez les changements par id. Les séances retirées sont gardées 30 jours : au-delà sans synchronisation, refaites un import complet.

Limites de débit

Chaque clé d’API a un quota de requêtes par fenêtre de 60 secondes, fixé par son offre. Les fenêtres commencent à chaque minute pleine (hh:mm:00).

Chaque réponse authentifiée donne le décompte exact de la clé :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 23
RateLimit-Policy: "standard";q=60;w=60
RateLimit: "standard";r=41;t=23

X-RateLimit-Remaining compte la requête en cours ; X-RateLimit-Reset est le nombre de secondes avant la fenêtre suivante. Les deux dernières lignes suivent le brouillon IETF RateLimit header fields.

Au-delà du quota, l’API répond 429 Too Many Requests avec Retry-After (secondes avant la fenêtre suivante) et X-RateLimit-Remaining: 0. Le corps détaille la limite :

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.",
    "details": { "limit": 60, "windowSeconds": 60, "retryAfterSeconds": 23, "plan": "standard" }
  }
}

Attendez Retry-After avant de réessayer : les requêtes refusées comptent aussi dans la fenêtre. Pour un quota plus élevé, contactez le support depuis le tableau de bord : répartir les requêtes sur plusieurs clés ou comptes pour le contourner enfreint les conditions d’utilisation.

Quota hebdomadaire

Certains comptes ont aussi un quota hebdomadaire, fixé par leur offre : un nombre de requêtes par semaine (lundi 00:00 UTC → dimanche), toutes les clés d’API du compte confondues. Quand votre compte en a un, chaque réponse porte :

X-Weekly-Quota-Limit: 10000
X-Weekly-Quota-Remaining: 8412
X-Weekly-Quota-Reset: 302400

X-Weekly-Quota-Remaining compte la requête en cours ; X-Weekly-Quota-Reset est le nombre de secondes avant lundi 00:00 UTC. Au-delà du quota, l’API répond 429 avec le code weekly_quota_exceeded et un Retry-After égal à ce délai ; les requêtes refusées ne comptent pas. Sans quota hebdomadaire, ces en-têtes sont absents.

Parcourir toutes les séances

Les listes de séances (/v1/showtimes, /v1/cinemas/{id}/showtimes, /v1/movies/{id}/showtimes) acceptent limit jusqu’à 1000. Pour tout parcourir, suivez le curseur plutôt qu’offset : l’ordre est stable (startsAt puis id) et chaque page répond aussi vite que la première.

curl "https://api.api-cinema.com/v1/showtimes?from=2026-09-16&to=2026-09-30&limit=1000" -H "Authorization: Bearer ac_live_…"
# meta.nextCursor = "WyIyMDI2LTA5LTE2VDE0OjAwOjAwIiwiLi4uIl0"
curl "https://api.api-cinema.com/v1/showtimes?from=2026-09-16&to=2026-09-30&limit=1000&cursor=WyIyMDI2LTA5LTE2VDE0OjAwOjAwIiwiLi4uIl0" -H "Authorization: Bearer ac_live_…"

Recommencez avec les mêmes filtres jusqu’à ce que meta.nextCursor vaille null. meta.total n’est calculé que sur la première page (sans curseur). Le curseur ne se combine ni avec offset ni avec near.

Serveur MCP

L’API est aussi disponible comme serveur MCP (Streamable HTTP), pour interroger les séances depuis Claude, Cursor ou tout client compatible. Le serveur prend la même clé d’API que l’API REST ; chaque appel d’outil compte comme une requête et suit la limite de débit de la clé.

Adresse : https://api.api-cinema.com/mcp

Claude Code

claude mcp add --transport http api-cinema https://api.api-cinema.com/mcp --header "Authorization: Bearer ac_live_…"

Claude Desktop, Cursor et clients configurés en JSON

{
  "mcpServers": {
    "api-cinema": {
      "type": "http",
      "url": "https://api.api-cinema.com/mcp",
      "headers": { "Authorization": "Bearer ac_live_…" }
    }
  }
}

Outils disponibles (lecture seule, 20 résultats par défaut)

• search_showtimes : Séances de cinéma à venir en France et aux États-Unis, filtrées par pays, par film (movie_id, identifiant TMDB ou Allociné), par ville, par distance autour d’un point, par jour ou plage horaire et par version. Chaque résultat inclut le film et le cinéma.
• search_cinemas : Cinémas en France et aux États-Unis par pays, ville, nom, code postal / ZIP code, ou autour d’un point (triés par distance, avec distanceKm).
• get_cinema : Fiche d’un cinéma (adresse, coordonnées, écrans, site, billetterie) par id ou slug.
• cinema_showtimes : Programme d’un cinéma, par id ou slug. Aujourd’hui par défaut.
• search_movies : Films par titre (sans tenir compte des accents ni de la casse). playing à true pour ne garder que les films avec des séances à venir, et country pour se limiter à un pays.
• movie_showtimes : Séances à venir d’un film, éventuellement dans un pays, une ville ou autour d’un point. Obtenez le movie_id avec search_movies.