# API delle serie TV > L'endpoint delle serie restituisce una serie per ID su GET /3/tv/{series_id}: nomi, trama, stato, stagioni, emittenti, generi e puntatori all'ultimo e al prossimo episodio. Il JSON segue TMDB v3, quindi i client esistenti richiedono solo un nuovo URL di base. Aggiungi append_to_response per unire classificazioni, crediti e valutazioni in una richiesta. ## Endpoint `GET /3/tv/{series_id}` ```bash curl "https://api.amodb.dev/3/tv/1396?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```json { "adult": false, "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg", "created_by": [], "episode_run_time": [ 48, 49 ], "first_air_date": "2008-01-20", "genres": [ { "id": 18, "name": "Drama" }, { "id": 80, "name": "Crime" } ], "homepage": "", "id": 1396, "in_production": false, "languages": [ "en" ], "last_air_date": "2013-09-29", "last_episode_to_air": { "air_date": "2013-09-29", "episode_number": 16, "episode_type": "standard", "id": 62161, "name": "פלינה", "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.", "production_code": "", "runtime": 56, "season_number": 5, "show_id": 1396, "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg", "vote_average": 0, "vote_count": 0 }, "name": "Breaking Bad", "next_episode_to_air": null, "networks": [ { "id": 174, "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png", "name": "AMC", "origin_country": "US" } ], "number_of_episodes": 62, "number_of_seasons": 5, "origin_country": [ "US" ], "original_language": "en", "original_name": "Breaking Bad", "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of only two years left to live. He becomes filled with a sense of fearlessness and an unrelenting desire to secure his family's financial...", "popularity": 268.4968, "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg", "production_companies": [ { "id": 2605, "logo_path": null, "name": "Gran Via Productions", "origin_country": "US" }, { "id": 11073, "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png", "name": "Sony Pictures Television", "origin_country": "US" }, { "id": 33742, "logo_path": "/2jdh2sEa0R6y6uT0F7g0IgA2WO8.png", "name": "High Bridge Productions", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" } ], "seasons": [ { "air_date": "2009-02-17", "episode_count": 9, "id": 3577, "name": "特别篇", "overview": "", "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg", "season_number": 0, "vote_average": 0 }, { "air_date": "2008-01-20", "episode_count": 7, "id": 3572, "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.", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 }, { "air_date": "2009-03-08", "episode_count": 13, "id": 3573, "name": "第 2 季", "overview": "贩卖冰毒的沃尔特老师在毒品交易中越陷越深，这引起了竞争对手的注意并使他在缉毒局的小舅子陷入危险中。", "poster_path": "/zMO024gJxKhTJfWqM0XTYd3SgKj.jpg", "season_number": 2, "vote_average": 0 } ], "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" }, { "english_name": "Spanish", "iso_639_1": "es", "name": "Español" } ], "status": "Ended", "tagline": "Change the equation.", "vote_average": 8.955, "vote_count": 18871 } ``` ## Ottenere i dettagli di una serie TV `GET /3/tv/{series_id}` restituisce la scheda di base di una serie: nomi, trama, stato, generi, emittenti, elenco delle stagioni e puntatori all'ultimo e al prossimo episodio. L'ID è l'ID numerico di serie TV di TMDB, quindi una serie che salvi come `1396` mantiene quell'ID qui. Gli ID di film e di serie TV sono spazi separati, quindi salva sempre il tipo di contenuto accanto al numero. L'esempio chiede Breaking Bad in inglese e aggiunge le sue classificazioni per età e i punteggi esterni nella stessa chiamata. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=content_ratings,ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ language: 'en-US', append_to_response: 'content_ratings,ratings' }); const res = await fetch(`https://api.amodb.dev/3/tv/1396?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const show = await res.json(); const us = show.content_ratings.results.find((r) => r.iso_3166_1 === 'US'); console.log(show.name, show.status, show.number_of_seasons, us?.rating); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396", params={"language": "en-US", "append_to_response": "content_ratings,ratings"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() show = r.json() us = next((x for x in show["content_ratings"]["results"] if x["iso_3166_1"] == "US"), None) print(show["name"], show["status"], show["number_of_seasons"], us and us["rating"]) ``` ```php 'en-US', 'append_to_response' => 'content_ratings,ratings', ]); $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => 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"); } $show = json_decode($body, true); echo $show['name'], ' ', $show['status'], ' ', $show['number_of_seasons'], PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type Show struct { Name string `json:"name"` Status string `json:"status"` NumberOfSeasons int `json:"number_of_seasons"` NumberOfEpisodes int `json:"number_of_episodes"` Next *struct { AirDate string `json:"air_date"` } `json:"next_episode_to_air"` } func main() { q := url.Values{"language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396?"+q.Encode(), 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 Show if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } next := "none scheduled" if s.Next != nil { next = s.Next.AirDate } fmt.Println(s.Name, s.Status, s.NumberOfSeasons, s.NumberOfEpisodes, next) } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | -------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------- | | `series_id` | percorso | sì | ID numerico della serie TV, per esempio `1396`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | | `language` | query | no | Tag TMDB come `en-US`, `uk-UA` o `es-ES`. Sono servite 14 lingue di base. Predefinito `en-US`. | | `append_to_response` | query | no | Elenco di sottorisorse separate da virgole da unire alla risposta, fino a 20 valori. | ### Campi della risposta | Campo | Tipo | Note | | -------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `id` | intero | ID della serie TV. | | `name`, `original_name` | stringa | Titolo localizzato e titolo originale. I nomi originali in giapponese o coreano restano in `original_name`. | | `overview`, `tagline` | stringa | Testo localizzato, vuoto quando non esiste una traduzione. | | `first_air_date`, `last_air_date` | stringa o null | `YYYY-MM-DD`. | | `status` | stringa | Ciclo di vita, vedi la tabella qui sotto. | | `in_production` | booleano | `true` finché la serie è ancora in lavorazione. | | `number_of_seasons`, `number_of_episodes` | intero | Totali, come salvati per la serie. | | `episode_run_time` | array | Durate tipiche degli episodi in minuti, può essere vuoto. | | `seasons` | array | Un riepilogo per stagione con `id`, `season_number`, `name`, `overview`, `episode_count`, `air_date`, `poster_path`, `vote_average`. | | `last_episode_to_air`, `next_episode_to_air` | oggetto o null | Riepiloghi di episodi, con la struttura degli oggetti di [stagioni ed episodi](https://amodb.dev/it/tv-seasons-episodes/). | | `networks`, `production_companies` | array | `id`, `name`, `logo_path`, `origin_country`. | | `production_countries`, `spoken_languages` | array | Paesi con `iso_3166_1` e `name`. Lingue con `english_name`, `iso_639_1` e `name`. | | `created_by` | array | Autori con `id`, `name`, `profile_path` e `credit_id`. Vuoto per la maggior parte delle serie. | | `genres` | array | Oggetti con `id` e `name`. Gli ID dei generi delle serie TV differiscono da quelli dei film. | | `origin_country`, `original_language`, `languages` | array, stringa | Codici paese e codici lingua. | | `homepage` | stringa | Sito ufficiale, vuoto quando non noto. | | `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/). | | `popularity` | numero | Punteggio relativo usato dalla lista dei popolari. | | `vote_average`, `vote_count` | numero, intero | Punteggio aggregato degli utenti. | | `adult` | booleano | Sempre `false`. I titoli per adulti non vengono mai serviti. | ### Risposta di esempio `GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings`, con array e testi lunghi accorciati: ```json { "adult": false, "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg", "created_by": [], "episode_run_time": [ 48, 49 ], "first_air_date": "2008-01-20", "genres": [ { "id": 18, "name": "Drama" }, { "id": 80, "name": "Crime" } ], "homepage": "", "id": 1396, "in_production": false, "languages": [ "en" ], "last_air_date": "2013-09-29", "last_episode_to_air": { "air_date": "2013-09-29", "episode_number": 16, "episode_type": "standard", "id": 62161, "name": "פלינה", "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.", "production_code": "", "runtime": 56, "season_number": 5, "show_id": 1396, "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg", "vote_average": 0, "vote_count": 0 }, "name": "Breaking Bad", "next_episode_to_air": null, "networks": [ { "id": 174, "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png", "name": "AMC", "origin_country": "US" } ], "number_of_episodes": 62, "number_of_seasons": 5, "origin_country": [ "US" ], "original_language": "en", "original_name": "Breaking Bad", "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of o...", "popularity": 268.4968, "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg", "production_companies": [ { "id": 2605, "logo_path": null, "name": "Gran Via Productions", "origin_country": "US" }, { "id": 11073, "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png", "name": "Sony Pictures Television", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" } ], "seasons": [ { "air_date": "2009-02-17", "episode_count": 9, "id": 3577, "name": "特别篇", "overview": "", "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg", "season_number": 0, "vote_average": 0 }, { "air_date": "2008-01-20", "episode_count": 7, "id": 3572, "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ], "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" }, { "english_name": "Spanish", "iso_639_1": "es", "name": "Español" } ], "status": "Ended", "tagline": "Change the equation.", "vote_average": 9, "vote_count": 18863, "content_ratings": { "results": [ { "descriptors": [], "iso_3166_1": "AT", "rating": "16" }, { "descriptors": [], "iso_3166_1": "AU", "rating": "MA 15+" } ] }, "ratings": { "imdb": { "value": 9.5, "votes": 2671962 }, "kinopoisk": { "value": 8.9, "votes": null }, "metacritic": null, "rotten_tomatoes": { "value": 96, "votes": null }, "tmdb": { "value": 9, "votes": 18863 } } } ``` I blocchi `content_ratings` e `ratings` vengono da `append_to_response`. Nomi e trame dentro `seasons`, `last_episode_to_air` e `next_episode_to_air` sono salvati per scheda e possono non seguire `language`, come mostra il nome di episodio in ebraico qui sopra. Leggi il testo localizzato di stagioni ed episodi dall'[endpoint della stagione](https://amodb.dev/it/tv-seasons-episodes/). ## Stato e puntatori degli episodi `status` ti dice a che punto è la vita di una serie, e `next_episode_to_air` ti dice quando ricontrollare. | Valore di `status` | Significato | `next_episode_to_air` | | -------------------------- | -------------------------------------------- | ---------------------------------------------------- | | `Returning Series` | In onda adesso o tra una stagione e l'altra. | Valorizzato quando una data è nota, altrimenti null. | | `Planned`, `In Production` | Non ancora una serie regolare. | Di solito null. | | `Ended` | Ha concluso il suo corso. | Null. | | `Canceled` | Interrotta prima della fine prevista. | Null. | Una serie in corso tra una stagione e l'altra ha un `next_episode_to_air` nullo, quindi leggi null come «nessuna data nota» e non come «conclusa». L'array `seasons` elenca un riepilogo per stagione, e la stagione `0` contiene gli speciali. Per leggere gli episodi di una stagione, chiama l'endpoint descritto in [stagioni ed episodi](https://amodb.dev/it/tv-seasons-episodes/). ## Endpoint correlati delle serie Tutti i percorsi condividono la base `https://api.amodb.dev/3`, e gli endpoint con testo localizzato accettano anche `language`. | Metodo e percorso | Restituisce | Parametri aggiuntivi | | ---------------------------------------- | ------------------------------------------------------------------------- | -------------------- | | `GET /tv/{series_id}/alternative_titles` | `{id, results}` con `iso_3166_1`, `title`, `type`, spesso vuoto | nessuno | | `GET /tv/{series_id}/content_ratings` | Classificazione per età per ogni paese | nessuno | | `GET /tv/{series_id}/episode_groups` | Elenco di ordinamenti alternativi degli episodi come DVD o arco narrativo | nessuno | | `GET /tv/{series_id}/recommendations` | Una lista di 20 serie consigliate | nessuno | | `GET /tv/{series_id}/similar` | Una lista di 20 serie simili | nessuno | | `GET /tv/{series_id}/reviews` | `results` è vuoto per la maggior parte delle serie | nessuno | | `GET /tv/{series_id}/lists` | Liste pubbliche che contengono la serie | `page` | | `GET /tv/{series_id}/watch/providers` | Piattaforme di streaming, noleggio e acquisto per paese | nessuno | | `GET /tv/latest` | L'ultima scheda di serie aggiunta | nessuno | Le liste di consigliati e simili restituiscono sempre la pagina 1 con 20 elementi. La risposta di `lists` è paginata con `page`, 20 liste per pagina. Le liste paginate altrove nell'API accettano `page` da 1 a 500. Le classificazioni per età tornano come voci `results` con `iso_3166_1`, `rating` e `descriptors`, quindi scegli la voce che corrisponde al paese dello spettatore. Le piattaforme di visione sono indicizzate per codice paese, e ogni paese contiene un `link` più le liste `flatrate`, `rent` e `buy` con `provider_id`, `provider_name`, `logo_path` e `display_priority`. Gli ID delle piattaforme per filtrare vengono dalle liste di riferimento in [generi e liste di riferimento](https://amodb.dev/it/genres/). La lista dei gruppi di episodi restituisce `id` (una stringa), `name`, `description`, `type`, `episode_count`, `group_count` e `network`. amodb elenca i gruppi ma non offre un endpoint che restituisca gli episodi di un gruppo. Non offre nemmeno i percorsi `changes` di TMDB. ## Unire più dati in una sola chiamata Elenca le sottorisorse in `append_to_response` e ciascuna arriva sotto la propria chiave. L'intera chiamata conta una volta nelle tue 20, 40 o 120 richieste al minuto. Funzionano fino a 20 valori, e i nomi sconosciuti vengono ignorati senza errore. Questi valori funzionano su una serie: | Valore | Aggiunge | Dettagli | | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `credits` | Cast e troupe | [Crediti](https://amodb.dev/it/credits/) | | `external_ids` | ID come `imdb_id`, `tvdb_id` e `wikidata_id` | [Ricerca per ID esterno](https://amodb.dev/it/find-by-external-id/) | | `images`, `videos` | Locandine, sfondi, trailer | [Immagini](https://amodb.dev/it/images-api/), [Video](https://amodb.dev/it/videos-trailers/) | | `keywords`, `translations` | Tag e testi tradotti | [Parole chiave](https://amodb.dev/it/keywords/), [Traduzioni](https://amodb.dev/it/translations/) | | `content_ratings`, `alternative_titles`, `episode_groups`, `lists`, `watch/providers`, `similar`, `recommendations`, `reviews` | Le sottorisorse della tabella qui sopra | Questa pagina | | `ratings`, `moods`, `soundtracks`, `wikidata`, `showtimes` | Extra di amodb | [Valutazioni](https://amodb.dev/it/ratings/), [Mood](https://amodb.dev/it/moods/), [Colonne sonore](https://amodb.dev/it/soundtracks/), [Orari delle proiezioni](https://amodb.dev/it/showtimes/) | ## Errori Una chiamata non riuscita restituisce il corpo di errore TMDB. Un ID sbagliato dà `status_code` 34 con il messaggio «The resource you requested could not be found.» | HTTP | status_code | Quando | | ---- | ----------- | ---------------------------------------------------------------------------- | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | Nessuna serie con quell'ID, un titolo per adulti, o un percorso non offerto. | | 405 | 37 | Hai chiamato un metodo di scrittura come valutare una serie. | | 429 | 25 | Oltre le tue richieste al minuto. Attendi i secondi di `Retry-After`. | L'elenco completo è in [errori](https://amodb.dev/it/errors/), e i limiti per piano sono in [limiti di richieste](https://amodb.dev/it/rate-limits/). ## Note pratiche - I dettagli di una serie e ogni sottorisorsa qui sopra restano in cache per 6 ore. Interroga `last_episode_to_air` al massimo poche volte al giorno. - Richiedi la lingua che mostri. Un `overview` vuoto significa che non esiste una traduzione, quindi richiedi di nuovo con `en-US` per un ripiego. - Usa `number_of_seasons` come limite del ciclo quando recuperi ogni stagione, una chiamata ciascuna. - Per elencare serie invece di leggerne una, vedi [ricerca](https://amodb.dev/it/search/), [discover](https://amodb.dev/it/discover/) e [tendenze e liste](https://amodb.dev/it/trending-lists/). ## Domande e risposte ### Come capisco se una serie è ancora in onda? Leggi status insieme a next_episode_to_air. Una serie in corso con un next_episode_to_air non nullo ha un episodio programmato. Le serie concluse e cancellate vi restituiscono sempre null, e può farlo anche una serie tra una stagione e l'altra. ### La scheda della serie include un ID IMDb? Non nella scheda di base, come in TMDB. Aggiungi append_to_response=external_ids per ottenere imdb_id e tvdb_id, oppure chiama l'endpoint find con un ID IMDb per passare da un ID esterno all'ID della serie. ### Posso ottenere i punteggi IMDb e Rotten Tomatoes di una serie? Sì. Chiama GET /3/tv/{series_id}/ratings o aggiungi append_to_response=ratings. Ottieni i punteggi IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB, ciascuno come value e votes, oppure null quando il punteggio non è noto. ### Per quanto tempo restano in cache i dati delle serie TV? I dettagli di una serie e le loro sottorisorse restano in cache sull'edge per 6 ore, quindi un episodio appena andato in onda può comparire in last_episode_to_air con quel ritardo. Le liste come quella delle serie in onda restano in cache 30 minuti. ## 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 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. - [Valutazioni di film e serie TV](https://amodb.dev/it/ratings/): API valutazioni film: punteggi IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB di un titolo in una chiamata, con null per le fonti non note. - [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. - [Errori](https://amodb.dev/it/errors/): Ogni errore di amodb con stato HTTP, status_code e messaggio TMDB, più la forma dell'errore OMDb. Cosa significa ciascuno e cosa deve fare il tuo client. - [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-19. Source: https://amodb.dev/it/tv-series/