# API delle collezioni > Una collezione raggruppa i film di una stessa saga, come una trilogia o una lunga serie di film. GET /3/collection/{collection_id} restituisce nome, trama, immagini e un array parts di film in ordine di uscita. I film rimandano alla loro collezione tramite belongs_to_collection, quindi puoi muoverti in entrambe le direzioni. ## Endpoint `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```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" } ] } ``` ## Ottenere una collezione `GET /3/collection/{collection_id}` restituisce una saga: nome, una trama, una locandina, un'immagine di sfondo e l'array `parts`. Ogni parte è un riepilogo di film con i campi che servono per una scheda, quindi una sola chiamata può disegnare un intero scaffale della saga. L'esempio carica la collezione 10, i film di Star Wars, e ne stampa i film in ordine di uscita. ```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) } } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | --------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | percorso | sì | ID numerico della collezione, per esempio `10`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | | `language` | query | no | Una delle 14 lingue servite, per esempio `en-US` o `fr-FR`. Imposta la lingua di titolo e trama di ogni parte. Predefinito `en-US`. | Il `name` e l'`overview` della collezione arrivano come salvati e non cambiano con `language`. Per alcune collezioni non sono in inglese. ### Campi della risposta | Campo | Tipo | Note | | ---------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- | | `id` | intero | ID della collezione. | | `name` | stringa | Nome della saga. | | `overview` | stringa | Breve descrizione. Vuota per alcune collezioni. | | `poster_path`, `backdrop_path` | stringa o null | Da accodare a `https://img.amodb.dev/t/p/{size}`. Vedi [immagini](https://amodb.dev/it/images-api/). | | `parts` | array | Riepiloghi dei film, prima la `release_date` più vecchia. | | `parts[].id` | intero | ID del film. Passalo ai [dettagli del film](https://amodb.dev/it/movies/). | | `parts[].title`, `parts[].original_title` | stringa | Titolo localizzato e titolo originale. | | `parts[].overview` | stringa | Sinossi localizzata. | | `parts[].release_date` | stringa | `YYYY-MM-DD`, o una stringa vuota per un film senza data. Queste parti vengono per ultime. | | `parts[].media_type` | stringa | Sempre `movie` in una collezione. | | `parts[].genre_ids` | array | ID numerici. I nomi vengono da [generi](https://amodb.dev/it/genres/). | | `parts[].adult`, `parts[].video` | booleano | `adult` è sempre `false`, perché i titoli per adulti non vengono serviti. | | `parts[].original_language` | stringa | Codice di lingua di due lettere. | | `parts[].popularity` | numero | Punteggio di popolarità. | | `parts[].poster_path`, `parts[].backdrop_path` | stringa o null | Immagini del film. | | `parts[].vote_average`, `parts[].vote_count` | numero, intero | Punteggio aggregato degli utenti. | ### Risposta di esempio Sono mostrate due delle nove parti. ```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" } ] } ``` Le stringhe lunghe sono tagliate con `...` per questa pagina. La risposta reale contiene il testo completo. ## Trovare la collezione di un film Raramente si parte dall'ID di una collezione. Si parte da un film, e la scheda dei [dettagli del film](https://amodb.dev/it/movies/) dice a cosa appartiene. Il campo `belongs_to_collection` è un oggetto con `id`, `name`, `poster_path` e `backdrop_path`. Vale `null` per un film che non fa parte di una saga, come il 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'esempio qui sotto segue quel collegamento da un film alla sua saga in due richieste. ```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); } ``` ## Immagini e ricerca La locandina e l'immagine di sfondo di una saga sono i campi `poster_path` e `backdrop_path` della scheda della collezione. Costruisci da essi l'indirizzo del file come descritto nella pagina [immagini](https://amodb.dev/it/images-api/). amodb non offre i percorsi `/collection/{collection_id}/images` e `/collection/{collection_id}/translations`, quindi una collezione non ha un elenco di locandine alternative né righe per lingua. I titoli delle parti seguono invece il parametro `language`, e [traduzioni](https://amodb.dev/it/translations/) tratta i percorsi che restituiscono righe per lingua. Per trovare una collezione per nome usa `GET /3/search/collection?query=matrix`, descritto nella pagina [ricerca](https://amodb.dev/it/search/). Ogni risultato ha `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` e `adult`. ## Errori | HTTP | status_code | Quando | | ---- | ----------- | ------------------------------------------------------------------------ | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | Nessuna collezione con quell'ID, o un ID che non è un numero. | | 405 | 37 | Hai usato un metodo di scrittura su un percorso di collezione. | | 429 | 25 | Hai superato le richieste al minuto. Attendi i secondi di `Retry-After`. | Vedi [errori](https://amodb.dev/it/errors/) per l'elenco completo e [limiti di richieste](https://amodb.dev/it/rate-limits/) per i limiti dei piani. ## Note pratiche - Le collezioni raggruppano solo film. Un film porta al massimo un oggetto `belongs_to_collection`, quindi un film corrisponde a una sola saga. - Le parti arrivano in ordine di uscita. I film con data vuota vengono per ultimi, quindi indicali come non ancora datati. - La scheda della collezione resta in cache sull'edge per 6 ore come gli altri dettagli, quindi una pagina della saga può riusare una risposta per tutto quel tempo. - Una parte porta solo campi di riepilogo. Recupera durata, crediti e valutazioni film per film tramite i [dettagli del film](https://amodb.dev/it/movies/) quando l'utente lo apre. - Usa `parts[].id` come chiave di un film, non la sua posizione nella saga. Ordini e date vengono corretti nel tempo. - Controlla che `name` sia nella tua lingua di visualizzazione prima di mostrarlo. Alcune collezioni hanno un nome in un'altra lingua, e `language` non lo cambia. ## Domande e risposte ### Come capisco se un film appartiene a una collezione? Leggi belongs_to_collection nella scheda dei dettagli del film. È un oggetto con id, name, poster_path e backdrop_path, oppure null quando il film è a sé stante. Usa quell'id nel percorso della collezione. ### Le parti vengono restituite in ordine di uscita? Sì. L'array parts arriva dal più vecchio per release_date. Un film senza data ha un release_date vuoto e finisce per ultimo, quindi indicalo come non ancora datato. ### Le serie TV hanno collezioni? No. Le collezioni raggruppano film. Una serie è descritta da stagioni ed episodi, documentati nelle pagine delle serie TV e di stagioni ed episodi. ### Come cerco una collezione per nome? Usa il percorso di ricerca delle collezioni, per esempio /3/search/collection?query=matrix. Restituisce una lista paginata con id, name e immagini. Prendi l'id e chiama l'endpoint della collezione per le parti. ## Pagine correlate - [API dei dettagli del film](https://amodb.dev/it/movies/): API dettagli film con gli stessi percorsi e JSON di TMDB v3. Ottieni un film per ID, aggiungi crediti, valutazioni e mood con append_to_response, in 14 lingue. - [API di ricerca](https://amodb.dev/it/search/): API di ricerca con percorsi e JSON di TMDB v3. Trova film, serie, persone, collezioni, società e parole chiave per testo, con filtri anno e paginazione. - [API delle immagini e host delle immagini](https://amodb.dev/it/images-api/): API immagini dei film con percorsi TMDB v3: elenca locandine, sfondi, loghi e fermi immagine di ogni titolo e caricali da img.amodb.dev in 10 dimensioni. - [API delle traduzioni](https://amodb.dev/it/translations/): API traduzioni con percorsi TMDB v3: leggi titoli, trame e slogan di un film, una serie o un episodio in tutte le loro lingue in una volta sola. - [API Discover](https://amodb.dev/it/discover/): API Discover con gli stessi filtri di TMDB v3. Elenca film e serie TV per genere, cast, società, parola chiave, anno, voto, durata e piattaforma. - [Avvio rapido](https://amodb.dev/it/quickstart/): Fai la prima chiamata ad amodb: ottieni una chiave, richiedi i dettagli di un film in curl, JavaScript, Python, PHP o Go, carica la locandina. Meno di 2 minuti. Aggiornato: 2026-10-18. Source: https://amodb.dev/it/collections/