# API di stagioni ed episodi delle serie TV > Leggi una stagione con ogni episodio su GET /3/tv/{series_id}/season/{season_number}, o un singolo episodio un livello più sotto. Il JSON segue TMDB v3 con air_date, episode_number, runtime e still_path. Ogni episodio porta crew e guest_stars, la stagione 0 contiene gli speciali, e append_to_response aggiunge crediti, immagini e video. ## Endpoint `GET /3/tv/{series_id}/season/{season_number}` ```bash curl "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```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 of lung cancer, he decides to team up with a former student and create a top of the line crystal meth in a used RV, to provide for his family once he is gone.", "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" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee313280006e8", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.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" }, { "character": "Jock", "credit_id": "52542275760ee313280006b4", "order": 500, "adult": false, "gender": 2, "id": 1216132, "known_for_department": "Acting", "name": "Aaron Hill", "original_name": "Aaron Hill", "popularity": 1.6521, "profile_path": "/rNp31SeoVqSQU6OZWxZUhGwAgyq.jpg" }, { "character": "Dr. Belknap", "credit_id": "52725cb1760ee3044d0b9984", "order": 502, "adult": false, "gender": 2, "id": 161591, "known_for_department": "Acting", "name": "Gregory Chase", "original_name": "Gregory Chase", "popularity": 0.5435, "profile_path": "/gNdodev00CROpXuAh5EFmkWTVOo.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 more complicated with the flip of a coin. Walt's wife, Skyler, becomes suspicious of Walt's strange behavior.", "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" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.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" }, { "character": "Ob-Gyn", "credit_id": "63012c9c5f4b73008267ba53", "order": 682, "adult": false, "gender": 0, "id": 1448105, "known_for_department": "Acting", "name": "Shane Marinson", "original_name": "Shane Marinson", "popularity": 0, "profile_path": null }, { "character": "Ben", "credit_id": "63012d2111c066007cbc37b1", "order": 683, "adult": false, "gender": 0, "id": 3670897, "known_for_department": "Acting", "name": "Jason Byrd", "original_name": "Jason Byrd", "popularity": 0, "profile_path": null } ] }, { "air_date": "2008-02-10", "episode_number": 3, "episode_type": "standard", "id": 62087, "name": "...And the Bag's in the River", "overview": "Walter fights with Jesse over his drug use, causing him to leave Walter alone with their captive, Krazy-8. Meanwhile, Hank has a scared straight moment with Walter Jr. after his aunt discovers he has been smoking pot. Also, Skylar is upset...", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/2kBeBlxGqBOdWlKwzAxiwkfU5on.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" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.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" }, { "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" }, { "character": "Carmen Molina", "credit_id": "52542273760ee31328000676", "order": 643, "adult": false, "gender": 1, "id": 115688, "known_for_department": "Acting", "name": "卡门·塞兰诺", "original_name": "卡门·塞兰诺", "popularity": 1.1342, "profile_path": "/nzJEe2UqvvMIBJZP1aeFEj4EunN.jpg" } ] } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Street-savvy former student Jesse Pinkman \"teaches\" Walter a new trade.", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Ottenere una stagione `GET /3/tv/{series_id}/season/{season_number}` restituisce una stagione e il suo array `episodes` completo in una sola risposta. I numeri di stagione partono da `1`, e `0` è riservato agli speciali. Prendi l'ID della serie e i numeri di stagione dalla scheda [serie TV](https://amodb.dev/it/tv-series/). L'esempio legge la stagione 1 di Breaking Bad. Il codice stampa una riga per episodio. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/tv/1396/season/1?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 season = await res.json(); for (const ep of season.episodes) { console.log(String(ep.episode_number).padStart(2, '0'), ep.name, ep.air_date, `${ep.runtime ?? '?'} min`); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396/season/1", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() season = r.json() for ep in season["episodes"]: print(f"{ep['episode_number']:02d}", ep["name"], ep["air_date"], ep["runtime"] or "?") ``` ```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"); } $season = json_decode($body, true); foreach ($season['episodes'] as $ep) { printf("%02d %s %s\n", $ep['episode_number'], $ep['name'], $ep['air_date']); } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Season struct { Name string `json:"name"` Episodes []struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` } `json:"episodes"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396/season/1?language=en-US", 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 s Season if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } for _, e := range s.Episodes { fmt.Printf("%02d %s %s %d min\n", e.EpisodeNumber, e.Name, e.AirDate, e.Runtime) } } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | -------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | `series_id` | percorso | sì | ID numerico della serie TV, per esempio `1396`. | | `season_number` | percorso | sì | Numero di stagione intero. `0` restituisce gli speciali. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | | `language` | query | no | Tag TMDB come `en-US` o `fr-FR`. Sono servite 14 lingue di base. Predefinito `en-US`. | | `append_to_response` | query | no | Valori a livello di stagione: `credits`, `external_ids`, `images`, `videos`. Gli altri nomi vengono ignorati. | ### Campi della risposta | Campo | Tipo | Note | | --------------------- | -------------- | ------------------------------------------------------------- | | `id`, `season_number` | intero | ID della stagione e il suo numero nella serie. | | `name`, `overview` | stringa | Testo localizzato, vuoto quando non esiste una traduzione. | | `air_date` | stringa o null | Data del primo episodio, `YYYY-MM-DD`. | | `poster_path` | stringa o null | Da accodare a `https://img.amodb.dev/t/p/{size}`. | | `vote_average` | numero | Punteggio aggregato degli utenti per la stagione. | | `episodes` | array | Ogni episodio, con i campi elencati nella sezione successiva. | ### Risposta di esempio `GET /3/tv/1396/season/1?language=en-US`. La stagione ha 7 episodi, quindi `episodes` è tagliato a una voce, e gli array `crew` e `guest_stars` di quella voce sono omessi: ```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 of lung cancer, he decides to...", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0 } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` Ogni episodio nella risposta della stagione porta anche gli array `crew` e `guest_stars`, con la struttura delle voci descritta nella pagina [crediti](https://amodb.dev/it/credits/). `runtime` può essere null per un episodio non ancora andato in onda. ## Ottenere un episodio `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` restituisce un episodio. La risposta della stagione contiene già ogni episodio con `crew` e `guest_stars`, quindi usa questo endpoint per aggiornare un record senza ricaricare la stagione. Accetta `language` e `append_to_response` con `credits`, `external_ids`, `images`, `translations` e `videos`. Una richiesta come `/3/tv/1396/season/1/episode/1?append_to_response=credits` costa una richiesta. | Campo | Tipo | Note | | --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | intero | ID dell'episodio. | | `show_id` | intero | ID della serie. Presente nella risposta della stagione e nei puntatori della serie, non nella risposta di un singolo episodio. | | `season_number`, `episode_number` | intero | Posizione nella serie. Usali per costruire il percorso della richiesta. | | `name`, `overview` | stringa | Testo localizzato. | | `air_date` | stringa o null | Solo la data, senza ora né fuso orario. Null quando non programmato. | | `episode_type` | stringa | `standard` per gli episodi normali. Per individuare un finale, confronta `episode_number` con l'`episode_count` di quella stagione nella scheda della serie. | | `runtime` | intero o null | Minuti. | | `production_code` | stringa | Codice dello studio, spesso vuoto. | | `still_path` | stringa o null | Immagine dell'episodio. Usa `w300` o `original` da `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count` | numero, intero | Punteggio aggregato degli utenti. | | `crew`, `guest_stars` | array | Crediti di questo episodio, vedi [crediti](https://amodb.dev/it/credits/). | ## Prossimo e ultimo episodio nella scheda della serie L'endpoint della serie restituisce `next_episode_to_air` e `last_episode_to_air`. Ognuno è un riepilogo di episodio con i campi qui sopra, più `show_id` e senza `crew` e `guest_stars`. Il prossimo è null per le serie concluse e per le serie in corso senza una data confermata. L'esempio legge South Park, una serie in corso. ```js const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; const res = await fetch('https://api.amodb.dev/3/tv/2190', { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const next = (await res.json()).next_episode_to_air; console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode'); ``` Per un conto alla rovescia, confronta `air_date` con la data locale dello spettatore. Il valore non porta l'ora del giorno, quindi mostra una data e non un orario. ## Sottorisorse di stagioni ed episodi I percorsi di stagioni ed episodi hanno le proprie sottorisorse. Diverse oggi restituiscono dati vuoti. | Metodo e percorso | Restituisce | | --------------------------------------------------------- | ---------------------------------------------------------- | | `GET /tv/{series_id}/season/{season_number}/credits` | `id`, `cast` e `crew` della stagione | | `GET /tv/{series_id}/season/{season_number}/images` | `id` e un array `posters` vuoto | | `GET /tv/{series_id}/season/{season_number}/videos` | `id` e un array `results` vuoto | | `GET /tv/{series_id}/season/{season_number}/external_ids` | `id` più `tvdb_id`, `wikidata_id` e altri ID, tutti nulli | | `GET /tv/{series_id}/season/{season_number}/translations` | `id` e un array `translations` vuoto | | `GET .../episode/{episode_number}/credits` | `id`, un `cast` vuoto, `crew` e `guest_stars` | | `GET .../episode/{episode_number}/images` | `id` e un array `stills` con l'immagine dell'episodio | | `GET .../episode/{episode_number}/videos` | `id` e un array `results` vuoto | | `GET .../episode/{episode_number}/external_ids` | `id` più `imdb_id`, `tvdb_id` e altri ID, tutti nulli | | `GET .../episode/{episode_number}/translations` | `id` e un array `translations` con nome e trama per lingua | I crediti di stagioni ed episodi sono trattati nella pagina [crediti](https://amodb.dev/it/credits/), e le immagini nella pagina [immagini](https://amodb.dev/it/images-api/). amodb non offre i percorsi `changes` di TMDB né un endpoint per gli episodi di un gruppo di episodi. ## Errori | HTTP | status_code | Quando | | ---- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | La serie, la stagione o l'episodio non esiste, per esempio la stagione `0` di una serie senza speciali, oppure il percorso non è offerto. | | 405 | 37 | Hai chiamato un metodo di scrittura. | | 429 | 25 | Oltre le tue richieste al minuto. Attendi i secondi di `Retry-After`. | Vedi [errori](https://amodb.dev/it/errors/) per il formato completo del corpo e [limiti di richieste](https://amodb.dev/it/rate-limits/) per le finestre. ## Note pratiche - Stagioni ed episodi restano in cache per 6 ore. Rileggi la stagione corrente una o due volte al giorno mentre una serie va in onda. - Una serie di 10 stagioni richiede 10 chiamate di stagione. Con il piano da 20 richieste al minuto consuma metà della disponibilità di un minuto, e una seconda esecuzione entro 6 ore viene servita dalla cache edge. - Un episodio non ancora andato in onda può avere `air_date` null, `runtime` null e `overview` vuoto. Mostra un segnaposto invece di fallire. - Le immagini degli episodi sono inquadrature larghe, non locandine. Chiedi `w300` per gli elenchi e `original` solo quando ti serve una vista a dimensione piena. ## Domande e risposte ### Come elenco ogni episodio di una serie? Leggi number_of_seasons dalla scheda della serie, poi chiama l'endpoint della stagione una volta per ogni numero di stagione. Ogni risposta di stagione porta il suo array episodes completo, quindi una serie di cinque stagioni richiede cinque richieste. ### Cosa significa il numero di stagione 0? La stagione 0 contiene gli speciali, come i dietro le quinte e i riepiloghi. Esiste solo quando la serie ha degli speciali, e una serie senza di essi restituisce 404 con status_code 34 per la stagione 0. ### Perché air_date è null per alcuni episodi? L'episodio è annunciato ma non ha ancora una data confermata. Tratta null come non programmato, e controlla next_episode_to_air nella scheda della serie per il prossimo episodio con data. ### Posso ottenere un ordine DVD o assoluto degli episodi? Non come elenco separato. GET /3/tv/{series_id}/episode_groups nomina gli ordinamenti che una serie ha, ma amodb non offre un endpoint che restituisca gli episodi di un gruppo. L'endpoint della stagione dà l'ordine standard. ## Pagine correlate - [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 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 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 guida agli episodi](https://amodb.dev/it/episode-guide-api/): API guida agli episodi con gli endpoint di stagioni ed episodi di TMDB v3: nomi, date, durate, immagini e gruppi di episodi di ogni serie, in 14 lingue. - [Limiti di richieste](https://amodb.dev/it/rate-limits/): amodb limita ogni chiave per richieste al minuto in una finestra scorrevole di 60 secondi: 20, 40 o 120 in base al piano. Leggi gli header, gestisci il 429. - [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/tv-seasons-episodes/