# API des collections > Une collection regroupe les films d'une même saga, comme une trilogie ou une longue série de films. GET /3/collection/{collection_id} renvoie son nom, son résumé, ses visuels et un tableau parts de films dans l'ordre de sortie. Les films renvoient à leur collection via belongs_to_collection : on circule dans les deux sens. ## Point de terminaison `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Réponse: ```json { "id": 10, "name": "Star Wars - Saga", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various characters \"a long time ago in a galaxy far, far away….\"", "poster_path": "/6mHkagjziBPth2Mx0VpEercocm4.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/jKquaxnCRelAbibZVMdTsUEnkKm.jpg", "genre_ids": [ 12, 28, 878 ], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to re...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23028, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empire, learns the ways of the Jedi from aging master Yoda. But Darth Vader is more determined than ever to capture Luke. Meanwhile, rebel leader Princess Le...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18993, "media_type": "movie" }, { "adult": false, "backdrop_path": "/ziECpBRIyclmBNaFSWlvCfsKbMD.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1892, "original_language": "en", "original_title": "Return of the Jedi", "overview": "Luke Skywalker leads a mission to rescue his friend Han Solo from the clutches of Jabba the Hutt, the Emperor prepares to crush the Rebellion with a more powerful Death Star, and the Rebel fleet mounts a massive attack on the space station....", "popularity": 26.3255, "poster_path": "/jQYlydvHm3kUix1f8prMucrplhm.jpg", "release_date": "1983-05-25", "title": "Return of the Jedi", "video": false, "vote_average": 7.911, "vote_count": 17442, "media_type": "movie" } ] } ``` ## Obtenir une collection `GET /3/collection/{collection_id}` renvoie une saga : son nom, un résumé, une affiche, une image de fond et le tableau `parts`. Chaque partie est un résumé de film avec les champs nécessaires pour une carte : un seul appel peut donc dessiner toute une étagère de saga. L'exemple charge la collection 10, les films Star Wars, et affiche ses films dans l'ordre de sortie. ```bash curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/collection/10?language=en-US'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const collection = await res.json(); console.log(collection.name); for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/collection/10", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() collection = r.json() print(collection["name"]) for p in collection["parts"]: print(p.get("release_date") or "not dated", p["title"]) ``` ```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"); } $collection = json_decode($body, true); echo $collection['name'], PHP_EOL; foreach ($collection['parts'] as $p) { echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Collection struct { Name string `json:"name"` Parts []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"parts"` } func main() { url := "https://api.amodb.dev/3/collection/10?language=en-US" 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 c Collection if err := json.NewDecoder(res.Body).Decode(&c); err != nil { panic(err) } fmt.Println(c.Name) for _, p := range c.Parts { date := p.ReleaseDate if date == "" { date = "not dated" } fmt.Println(date, p.Title) } } ``` ### Paramètres | Paramètre | Dans | Requis | Description | | --------------- | ------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | chemin | oui | Identifiant numérique de la collection, par exemple `10`. | | `api_key` | requête | l'un des deux | Votre clé. Utilisez-la ou l'en-tête `Authorization: Bearer`. | | `language` | requête | non | L'une des 14 langues servies, par exemple `en-US` ou `fr-FR`. Fixe la langue du titre et du résumé de chaque partie. Par défaut `en-US`. | Le `name` et l'`overview` propres à la collection sont fournis tels que stockés et ne changent pas avec `language`. Pour certaines collections, ils ne sont pas en anglais. ### Champs de la réponse | Champ | Type | Remarques | | ---------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | | `id` | entier | Identifiant de la collection. | | `name` | chaîne | Nom de la saga. | | `overview` | chaîne | Courte description. Vide pour certaines collections. | | `poster_path`, `backdrop_path` | chaîne ou null | À ajouter à `https://img.amodb.dev/t/p/{size}`. Voir [images](https://amodb.dev/fr/images-api/). | | `parts` | tableau | Résumés de films, `release_date` la plus ancienne en premier. | | `parts[].id` | entier | Identifiant du film. Passez-le aux [détails d'un film](https://amodb.dev/fr/movies/). | | `parts[].title`, `parts[].original_title` | chaîne | Titre localisé et titre original. | | `parts[].overview` | chaîne | Synopsis localisé. | | `parts[].release_date` | chaîne | `YYYY-MM-DD`, ou une chaîne vide pour un film sans date. Ces parties viennent en dernier. | | `parts[].media_type` | chaîne | Toujours `movie` dans une collection. | | `parts[].genre_ids` | tableau | Identifiants numériques. Les noms viennent de [genres](https://amodb.dev/fr/genres/). | | `parts[].adult`, `parts[].video` | booléen | `adult` vaut toujours `false`, car les titres pour adultes ne sont pas servis. | | `parts[].original_language` | chaîne | Code de langue à deux lettres. | | `parts[].popularity` | nombre | Score de popularité. | | `parts[].poster_path`, `parts[].backdrop_path` | chaîne ou null | Visuels du film. | | `parts[].vote_average`, `parts[].vote_count` | nombre, entier | Note agrégée des utilisateurs. | ### Exemple de réponse Deux des neuf parties sont montrées. ```json { "id": 10, "name": "Star Wars Collection", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg", "genre_ids": [12, 28, 878], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23025, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [12, 28, 878], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18990, "media_type": "movie" } ] } ``` Les longues chaînes sont coupées avec `...` pour cette page. La vraie réponse contient le texte complet. ## Trouver la collection d'un film On part rarement d'un identifiant de collection. On part d'un film, et la fiche de [détails du film](https://amodb.dev/fr/movies/) indique à quoi il appartient. Le champ `belongs_to_collection` est un objet avec `id`, `name`, `poster_path` et `backdrop_path`. Il vaut `null` pour un film qui ne fait pas partie d'une saga, comme le film 550. ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` L'exemple ci-dessous suit ce lien d'un film à sa saga en deux requêtes. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function getJson(path) { const res = await fetch(`${base}${path}`, { headers }); if (!res.ok) throw new Error(`${path} returned ${res.status}`); return res.json(); } const movie = await getJson('/movie/11'); if (movie.belongs_to_collection) { const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`); console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name); } ``` ## Visuels et recherche L'affiche et l'image de fond d'une saga sont les champs `poster_path` et `backdrop_path` de la fiche de collection. Construisez-en l'adresse du fichier comme décrit sur [images](https://amodb.dev/fr/images-api/). amodb ne propose pas les chemins `/collection/{collection_id}/images` et `/collection/{collection_id}/translations` : une collection n'a donc ni liste d'affiches alternatives ni lignes par langue. Les titres des parties suivent plutôt le paramètre `language`, et [traductions](https://amodb.dev/fr/translations/) couvre les chemins qui renvoient des lignes par langue. Pour trouver une collection par son nom, utilisez `GET /3/search/collection?query=matrix`, décrit sur [recherche](https://amodb.dev/fr/search/). Chaque résultat a `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` et `adult`. ## Erreurs | 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 | Aucune collection avec cet identifiant, ou un identifiant qui n'est pas un nombre. | | 405 | 37 | Vous avez utilisé une méthode d'écriture sur un chemin de collection. | | 429 | 25 | Vous avez dépassé vos requêtes par minute. Attendez les secondes de `Retry-After`. | Voir [erreurs](https://amodb.dev/fr/errors/) pour la liste complète et [limites de débit](https://amodb.dev/fr/rate-limits/) pour les limites des offres. ## Remarques pratiques - Les collections ne regroupent que des films. Un film porte au plus un objet `belongs_to_collection` : un film correspond donc à une seule saga. - Les parties arrivent dans l'ordre de sortie. Les films dont la date est vide viennent en dernier : indiquez donc qu'ils ne sont pas encore datés. - La fiche de collection est mise en cache 6 heures en périphérie comme les autres détails : une page de saga peut donc réutiliser une réponse pendant tout ce temps. - Une partie ne porte que des champs de résumé. Récupérez la durée, la distribution et les notes film par film via les [détails du film](https://amodb.dev/fr/movies/) quand l'utilisateur l'ouvre. - Utilisez `parts[].id` comme clé d'un film, pas sa position dans la saga. Les ordres et les dates sont corrigés avec le temps. - Vérifiez que `name` est dans votre langue d'affichage avant de l'afficher. Certaines collections portent un nom dans une autre langue, et `language` ne le change pas. ## Questions et réponses ### Comment savoir si un film appartient à une collection ? Lisez belongs_to_collection dans la fiche de détails du film. C'est un objet avec id, name, poster_path et backdrop_path, ou null quand le film est isolé. Utilisez cet id dans le chemin de la collection. ### Les parties sont-elles renvoyées dans l'ordre de sortie ? Oui. Le tableau parts arrive du plus ancien au plus récent selon release_date. Un film sans date a un release_date vide et se place en dernier : indiquez donc qu'il n'est pas encore daté. ### Les séries ont-elles des collections ? Non. Les collections regroupent des films. Une série est décrite par ses saisons et ses épisodes, documentés sur les pages des séries TV et des saisons et épisodes. ### Comment chercher une collection par son nom ? Utilisez le chemin de recherche de collections, par exemple /3/search/collection?query=matrix. Il renvoie une liste paginée avec id, name et visuels. Prenez l'id et appelez le point de terminaison de la collection pour les parties. ## Pages liées - [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. - [API de recherche](https://amodb.dev/fr/search/): API de recherche aux chemins et au JSON de TMDB v3 : films, séries, personnes, collections, sociétés et mots-clés par texte, filtres d'année et pagination. - [API d'images et hôte d'images](https://amodb.dev/fr/images-api/): API d'images de films aux chemins TMDB v3 : listez affiches, fonds, logos et images par titre, puis chargez-les depuis img.amodb.dev en 10 tailles sans clé. - [API des traductions](https://amodb.dev/fr/translations/): API de traductions aux chemins TMDB v3 : lisez titres, résumés et slogans d'un film, d'une série ou d'un épisode dans toutes ses langues à la fois. - [API Discover](https://amodb.dev/fr/discover/): API Discover avec les mêmes filtres que TMDB v3. Listez films et séries par genre, distribution, société, mot-clé, année, note, durée et plateforme. - [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/collections/