# API guida agli episodi > L'API della guida agli episodi elenca ogni episodio di una serie tramite GET /3/tv/{tv_id}/season/{season_number}. Ogni episodio ha nome, trama, data di messa in onda, durata e immagine. La lista episode_groups nomina gli ordinamenti alternativi come DVD o assoluto. Percorsi e JSON seguono TMDB v3, quindi i client esistenti richiedono solo un nuovo URL di base. ## Ottenere tutti gli episodi di una stagione `GET /3/tv/{tv_id}/season/{season_number}` restituisce una stagione con il suo array `episodes` completo. Ogni episodio ha `episode_number`, `name`, `overview`, `air_date`, `runtime` e `still_path`. Gli ID sono gli ID numerici usati da TMDB, per esempio `1396` per Breaking Bad. Ottieni stagioni, episodi con date e durate, immagini, il prossimo e l'ultimo episodio andati in onda di una serie, e l'elenco degli ordinamenti alternativi degli episodi. I campi di testo seguono il parametro `language`, e una trama resta vuota quando non esiste una traduzione. ## Quali dati ottieni | Endpoint | Restituisce | | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `GET /3/tv/{tv_id}` | Il riepilogo `seasons`, `number_of_seasons`, `status`, `next_episode_to_air`, `last_episode_to_air` | | `GET /3/tv/{tv_id}/season/{season_number}` | Una stagione con tutti i suoi `episodes` | | `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}` | Un episodio con `crew` e `guest_stars` | | `GET /3/tv/{tv_id}/episode_groups` | Nome, `type` e numero di episodi di ogni ordinamento alternativo definito per la serie | Campi di un episodio: | Campo | Tipo | Note | | --------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `id`, `show_id` | intero | ID dell'episodio e della serie. `show_id` è nelle liste delle stagioni e in `next_episode_to_air`, non sul percorso del singolo episodio | | `episode_number`, `season_number` | intero | Posizione nella stagione | | `episode_type` | stringa | Per esempio `standard` | | `name`, `overview` | stringa | Localizzati con `language` | | `air_date` | stringa o null | `YYYY-MM-DD`, vuota o null quando non annunciata | | `runtime` | intero o null | Minuti | | `still_path` | stringa o null | Da unire a `https://img.amodb.dev/t/p/{size}` | | `vote_average`, `vote_count` | numero, intero | Attualmente `0` sugli episodi | | `production_code` | stringa | Codice dello studio, spesso vuoto | | `crew`, `guest_stars` | array | Persone accreditate nell'episodio, con gli stessi campi di un membro del cast | ## Parti in 3 passaggi 1. Scegli un piano nella pagina dei [prezzi](https://amodb.dev/it/pricing/). Tutti i piani restituiscono gli stessi dati sugli episodi, cambia solo la frequenza delle richieste. 2. Crea una chiave nella dashboard del tuo account e salvala in una variabile d'ambiente. 3. Richiedi `/3/tv/{tv_id}/season/1` con la chiave come header Bearer o in `api_key`. ## Esempio di richiesta L'esempio recupera la stagione 1 di Breaking Bad (ID serie `1396`) in inglese. Il programma in Go la decodifica in struct tipizzate e stampa una riga per episodio con la data di messa in onda, la durata e l'URL dell'immagine. ```bash curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Episode struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` StillPath *string `json:"still_path"` } type Season struct { Name string `json:"name"` SeasonNumber int `json:"season_number"` Episodes []Episode `json:"episodes"` } func main() { client := &http.Client{Timeout: 10 * time.Second} url := "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" req, err := http.NewRequest("GET", url, nil) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(fmt.Sprintf("amodb returned %s", res.Status)) } var season Season if err := json.NewDecoder(res.Body).Decode(&season); err != nil { panic(err) } fmt.Println(season.Name) for _, e := range season.Episodes { still := "no still" if e.StillPath != nil { still = "https://img.amodb.dev/t/p/w300" + *e.StillPath } fmt.Printf("S%02dE%02d %s %3d min %s %s\n", season.SeasonNumber, e.EpisodeNumber, e.AirDate, e.Runtime, e.Name, still) } } ``` Risposta ridotta: 2 dei 7 episodi, con un membro della troupe e un ospite ciascuno. ```json { "air_date": "2008-01-20", "episodes": [ { "air_date": "2008-01-20", "episode_number": 1, "episode_type": "standard", "id": 62085, "name": "Pilot", "overview": "When an unassuming high school chemistry teacher discovers he has a rare form...", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7029219c29533d00dd2c1", "adult": false, "gender": 2, "id": 2483, "known_for_department": "Camera", "name": "约翰·托尔", "original_name": "约翰·托尔", "popularity": 1.1957, "profile_path": "/cfL9A6tC7L5Ps5fq1o3WpVKGMb1.jpg" } ], "guest_stars": [ { "character": "Steven Gomez", "credit_id": "5271b489760ee35b3e0881a7", "order": 8, "adult": false, "gender": 2, "id": 61535, "known_for_department": "Acting", "name": "史蒂文·迈克尔·奎扎达", "original_name": "史蒂文·迈克尔·奎扎达", "popularity": 1.7511, "profile_path": "/pVYrDkwI6GWvCNL2kJhpDJfBFyd.jpg" } ] }, { "air_date": "2008-01-27", "episode_number": 2, "episode_type": "standard", "id": 62086, "name": "Cat's in the Bag...", "overview": "Walt and Jesse attempt to tie up loose ends. The desperate situation gets mor...", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/AbMoecO0ZZio0LcgeLxlzdyGs6X.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7049c19c2953b63015013", "adult": false, "gender": 2, "id": 17948, "known_for_department": "Camera", "name": "Reynaldo Villalobos", "original_name": "Reynaldo Villalobos", "popularity": 0.904, "profile_path": "/4YlfhHDRZWhbRgeqT2Bwl1u5p9j.jpg" } ], "guest_stars": [ { "character": "Krazy-8", "credit_id": "52725845760ee3046b09426e", "order": 504, "adult": false, "gender": 2, "id": 1046460, "known_for_department": "Acting", "name": "Max Arciniega", "original_name": "Max Arciniega", "popularity": 1.4399, "profile_path": "/eqKAJKPpt41KpsLIkkBnAY4HMAL.jpg" } ] } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Recuperare un'intera serie amodb non accetta valori del tipo `season/1` in `append_to_response`, quindi le chiamate delle stagioni restano separate. Leggi prima `number_of_seasons` e la lista `seasons` dai dettagli della serie, poi richiedi ogni stagione in un ciclo. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path) { const res = await fetch(base + path, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const show = await get('/tv/1396'); for (const { season_number } of show.seasons) { const season = await get(`/tv/1396/season/${season_number}`); console.log(season.name, season.episodes.length); } ``` `seasons` include la stagione 0 quando la serie ha degli speciali, quindi Breaking Bad costa 1 chiamata di dettagli più 6 chiamate di stagione. Una serie con 10 stagioni costa 11 richieste. I dettagli restano in cache sull'edge per 6 ore, quindi salva il risultato e aggiornalo a intervalli. ## Date di messa in onda e cosa viene dopo `GET /3/tv/{tv_id}` contiene `next_episode_to_air` e `last_episode_to_air`, oggetti episodio completi con `name`, `air_date`, `season_number`, `episode_number`, `runtime` e `still_path`. `next_episode_to_air` vale `null` quando non è annunciato nulla. Combinalo con `status` (per esempio `Returning Series`, `Ended` o `Canceled`) per decidere se mostrare un conto alla rovescia. `air_date` è una data di calendario senza ora. Confrontala con la data di oggi per segnalare i nuovi episodi. Per un palinsesto di ciò che è in onda, le liste `airing_today` e `on_the_air` nella pagina [tendenze e liste](https://amodb.dev/it/trending-lists/) restano in cache per 30 minuti. ## Immagini e durate Usa `w185` o `w300` per le righe degli elenchi e `original` per la dimensione piena. Le dimensioni delle immagini degli episodi sono `w92`, `w185`, `w300` e `original`. Un episodio può non avere un'immagine, quindi mostra un segnaposto quando `still_path` è `null`. L'host delle immagini non richiede alcuna chiave, vedi [immagini](https://amodb.dev/it/images-api/). `runtime` è in minuti e può essere `null`. Per mostrare il tempo di una maratona su una stagione, somma `runtime` su `episodes` contando `null` come 0. Aggiungi `append_to_response=credits,images` al percorso del singolo episodio per ottenere un oggetto `credits` e una lista `stills`. L'array `cast` dell'episodio è vuoto, e le persone stanno in `crew` e `guest_stars`. I dettagli sono nelle pagine [stagioni ed episodi](https://amodb.dev/it/tv-seasons-episodes/) e [crediti](https://amodb.dev/it/credits/). ## Ordinamenti alternativi con i gruppi di episodi Alcune serie si guardano in un ordine diverso da quello della messa in onda. `GET /3/tv/{tv_id}/episode_groups` elenca gli ordinamenti definiti per una serie. Ogni voce ha `id`, `name`, `description`, `type`, `episode_count`, `group_count` e `network`. L'array `results` è vuoto quando non ne è definito nessuno. | `type` | Ordinamento | | ------ | ------------------------------- | | 1 | Data di messa in onda originale | | 2 | Assoluto | | 3 | DVD | | 4 | Digitale | | 5 | Arco narrativo | | 6 | Produzione | | 7 | TV | amodb restituisce solo questa lista. Non offre `GET /3/tv/episode_group/{id}`, quindi gli episodi all'interno di un gruppo non sono disponibili. Usa gli endpoint delle stagioni per i dati sugli episodi. ## Confronto | Funzionalità | Fare scraping delle pagine degli episodi | API di metadati con piano gratuito | amodb | | ------------------------------- | ---------------------------------------- | ---------------------------------- | -------------------------------------------------------- | | Stagione completa | Una pagina da scaricare per stagione | Vedi la loro documentazione | Una sola chiamata, array `episodes` incluso | | Serie intera | Scansionare ogni stagione | Vedi la loro documentazione | Una chiamata per stagione, elencate in `seasons` | | Date di messa in onda | Analizzare il testo | Vedi la loro documentazione | `air_date` più `next_episode_to_air` | | Immagini | Scaricare e ridimensionare | Vedi la loro documentazione | Dimensioni fisse su `img.amodb.dev`, senza chiave | | Altri ordinamenti degli episodi | Non disponibile | Vedi la loro documentazione | Lista `episode_groups`, contenuto dei gruppi non servito | | Lingue | Una lingua per sito | Vedi la loro documentazione | 14 lingue tramite `language` | ## Prezzi I piani sono prepagati per 1, 3, 6, 12 o 24 mesi, con uno sconto di 0, 10, 20, 30 o 40 per cento per i periodi più lunghi, e non si rinnovano mai da soli. I piani da 20, 40 e 120 richieste al minuto restituiscono tutti gli endpoint di questa pagina. Aggiornare una serie costa una richiesta per i dettagli e una per stagione. Non esiste un piano gratuito. Scegli un piano nella pagina dei [prezzi](https://amodb.dev/it/pricing/). ## Domande e risposte ### Come elenco tutti gli episodi di una serie TV? Leggi number_of_seasons da GET /3/tv/{tv_id}, poi chiama GET /3/tv/{tv_id}/season/{season_number} per ogni stagione. Ogni risposta di stagione contiene l'array episodes completo, quindi non serve una chiamata separata per episodio. Alcune stagioni tornano con un array episodes vuoto quando non ci sono dati sugli episodi. ### Posso ottenere più stagioni in una sola richiesta? No. amodb ignora i valori del tipo season/1 in append_to_response, quindi ogni stagione è una richiesta a sé. Una serie con 10 stagioni costa 11 richieste, una per i dettagli e una per stagione. ### Cos'è un gruppo di episodi? Un gruppo di episodi è un ordinamento alternativo degli stessi episodi, come l'ordine DVD, assoluto o per arco narrativo. GET /3/tv/{tv_id}/episode_groups li elenca con nome, tipo e numero di episodi. amodb non serve gli episodi all'interno di un gruppo. ### Come scopro quando va in onda il prossimo episodio? GET /3/tv/{tv_id} restituisce next_episode_to_air con il suo air_date, season_number ed episode_number. Il valore è null quando non è annunciato nulla. last_episode_to_air dà il più recente. ### Da dove vengono le immagini degli episodi? Ogni episodio ha uno still_path. Uniscilo a https://img.amodb.dev/t/p/{size}, per esempio w300 per le righe di un elenco. Le immagini non richiedono alcuna chiave. Uno still_path può essere null, quindi tieni pronto un segnaposto. ## Pagine correlate - [API di stagioni ed episodi delle serie TV](https://amodb.dev/it/tv-seasons-episodes/): API stagioni ed episodi con gli stessi percorsi e JSON di TMDB v3. Leggi una stagione con tutti gli episodi, o un episodio con data, durata e immagine. - [API delle serie TV](https://amodb.dev/it/tv-series/): API serie TV con gli stessi percorsi e JSON di TMDB v3. Ottieni una serie per ID con stagioni, emittenti e prossimo episodio, più classificazioni e piattaforme. - [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 dei crediti](https://amodb.dev/it/credits/): API crediti con gli stessi percorsi e JSON di TMDB v3. Ottieni cast e troupe di film, serie, stagioni ed episodi, con i campi order, department e job. - [API per serie TV, stagioni ed episodi](https://amodb.dev/it/tv-show-api/): API serie TV con stato, emittenti, stagioni, episodi e next_episode_to_air. JSON compatibile TMDB v3 in 14 lingue, da 20 richieste al minuto. - [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/episode-guide-api/