# API per serie TV, stagioni ed episodi > L'API per le serie TV restituisce una serie su GET /3/tv/{series_id} con stato, emittenti, elenco delle stagioni e next_episode_to_air. Gli endpoint di stagioni ed episodi aggiungono date di messa in onda, durate e immagini. Il JSON segue TMDB v3, in 14 lingue, con piani prepagati da 20, 40 o 120 richieste al minuto. ## Un'API per serie TV con stato, stagioni e prossimo episodio `GET /3/tv/{series_id}` restituisce una serie con il suo `status`, le sue `networks`, l'elenco `seasons`, `last_episode_to_air` e `next_episode_to_air`. Gli endpoint di stagioni ed episodi aggiungono date di messa in onda, durate e immagini. amodb è un'API indipendente che parla il protocollo TMDB v3, quindi un client scritto per TMDB funziona dopo che hai cambiato l'URL di base in `https://api.amodb.dev/3`. Cosa ottieni: - Schede di serie con il numero di stagioni ed episodi, più le date della prima e dell'ultima messa in onda. - Una stringa `status` e un flag `in_production`. - Emittenti con ID, loghi e paese di origine. - Una chiamata per stagione, che restituisce tutti gli episodi di quella stagione. - Liste di serie in onda oggi o nei prossimi 7 giorni. ## Quali dati ottieni | Ti serve | Chiamata | Campi principali | | -------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Scheda della serie | `GET /3/tv/{series_id}` | `name`, `original_name`, `status`, `in_production`, `number_of_seasons`, `number_of_episodes` | | Prossimo e ultimo episodio | stessa chiamata | `next_episode_to_air`, `last_episode_to_air` | | Una stagione | `GET /3/tv/{series_id}/season/{season_number}` | `episodes`, `air_date`, `poster_path` | | Un episodio | `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` | `name`, `overview`, `runtime`, `still_path`, `air_date` | | Un'emittente | `GET /3/network/{network_id}` | `name`, `headquarters`, `origin_country` | Gli elenchi completi dei campi sono nelle pagine [serie TV](https://amodb.dev/it/tv-series/) e [stagioni ed episodi](https://amodb.dev/it/tv-seasons-episodes/). ## Parti in 3 passaggi 1. Apri la pagina dei [prezzi](https://amodb.dev/it/pricing/) e scegli il piano con la frequenza di richieste che ti serve: 20, 40 o 120 al minuto. 2. Crea una chiave API nella dashboard del tuo account. 3. Invia `GET /3/tv/{series_id}` con `Authorization: Bearer YOUR_API_KEY`, oppure aggiungi `api_key` come parametro di query. ## Esempio di richiesta Lo script legge Breaking Bad (ID serie 1396), stampa il suo stato e il prossimo episodio, poi elenca la stagione 1. Salvalo come `check.mjs` ed eseguilo con Node 18 o successivo. ```bash curl -s "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=ratings" \ -H "Authorization: Bearer $AMODB_KEY" curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```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?language=en-US'); const next = show.next_episode_to_air; console.log(`${show.name}: ${show.status}, ${show.number_of_seasons} seasons`); console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode is scheduled'); const season = await get('/tv/1396/season/1?language=en-US'); for (const ep of season.episodes) { console.log(`E${ep.episode_number} ${ep.air_date} ${ep.name}`); } ``` Una risposta di serie ridotta per `language=en-US`. Sono tenuti solo alcuni campi, e `seasons` mostra le sue prime 2 voci su 6. Alcuni nomi in questi dati non seguono `language`: il nome della stagione 0 è in cinese e il `name` dentro `last_episode_to_air` è in ebraico. ```json { "first_air_date": "2008-01-20", "id": 1396, "in_production": false, "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, "number_of_episodes": 62, "number_of_seasons": 5, "original_name": "Breaking Bad", "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 diagn...", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ], "status": "Ended" } ``` ## Leggere lo stato e il prossimo episodio La stringa `status` ti dice come etichettare una serie. `next_episode_to_air` è un oggetto solo mentre un episodio è programmato, quindi è null tra una stagione e l'altra oltre che dopo la fine. Controlla `status` prima di mostrare «conclusa». | `status` | Significato | Cosa mostrare | | ---------------- | ------------------------------------ | ------------------------------------------------------------------------------ | | Returning Series | Sono attesi altri episodi | La prossima data di messa in onda se l'oggetto esiste, altrimenti «in ritorno» | | In Production | In lavorazione, non ancora in onda | «In produzione» | | Planned | Solo annunciata | «Pianificata» | | Pilot | Esiste solo un pilot | «Pilot» | | Ended | La serie è finita | «Conclusa» e `last_air_date` | | Canceled | Interrotta prima della fine prevista | «Cancellata» | Campi dentro `next_episode_to_air` e `last_episode_to_air`: `air_date`, `season_number`, `episode_number`, `episode_type`, `id`, `show_id`, `name`, `overview`, `runtime` e `still_path`. La stringa `status` può anche essere vuota su alcuni titoli, quindi tieni pronta un'etichetta neutra. I dettagli restano in cache sull'edge per 6 ore, quindi chiedere la stessa serie più di quattro volte al giorno restituisce lo stesso corpo. Interroga le serie che segui una o due volte al giorno e aggiorna quella che un utente apre. ## Stagioni, episodi e cosa è in onda La stagione 0, quando una serie ne ha una, contiene gli speciali. Le stagioni normali iniziano da 1. | Chiamata | Restituisce | Parametri | | ---------------------------------------------- | --------------------------------------------- | ------------------------------------------------- | | `GET /3/tv/{series_id}/season/{season_number}` | Scheda della stagione con un array `episodes` | `language`, `append_to_response` | | `GET /3/tv/airing_today` | Serie con un episodio in onda oggi | `page`, `language` | | `GET /3/tv/on_the_air` | Serie in onda nella prossima settimana | `page`, `language` | | `GET /3/discover/tv` | Serie filtrate per emittente, stato e altro | `with_networks`, `with_status`, `sort_by`, `page` | Liste e risultati di discover restano in cache 30 minuti, quindi una richiesta ogni mezz'ora basta per un badge «in onda a breve». Confronta gli ID restituiti con le serie che seguono i tuoi utenti. Dettagli di stagioni ed episodi sono trattati nella pagina della [guida agli episodi](https://amodb.dev/it/episode-guide-api/). ## Costruire una lista di serie seguite con conti alla rovescia Una schermata «le serie che seguo» richiede un ID salvato per serie e un piccolo job giornaliero. 1. Salva l'`id` della serie quando un utente la segue. 2. Una volta al giorno chiama `/3/tv/{series_id}` per ogni ID seguito e salva `status`, `next_episode_to_air` e `last_air_date`. 3. Quando `next_episode_to_air` è un oggetto, mostra `air_date` come data. Non porta né ora né fuso orario, quindi non fare il conto alla rovescia al minuto. 4. Quando è null e `status` è Returning Series, mostra «nuova stagione non programmata». 5. Chiama la stagione solo quando un utente apre la serie, perché è la risposta più grande. Un 404 con `status_code` 34 significa che l'ID è sconosciuto, e un 429 significa che hai superato le richieste al minuto: attendi i secondi di `Retry-After`. Con 200 serie seguite, un passaggio giornaliero sono 200 richieste, circa dieci minuti a 20 richieste al minuto. Vedi [limiti di richieste](https://amodb.dev/it/rate-limits/) ed [errori](https://amodb.dev/it/errors/). ## Confronto | Funzionalità | Fare scraping delle pagine da solo | API di metadati con piano gratuito | amodb | | -------------------------------- | ------------------------------------ | ----------------------------------- | ---------------------------------------------------------- | | Struttura di stagioni ed episodi | Ricostruita dai layout delle pagine | Varia, vedi la documentazione | Chiamata di stagione con un array `episodes` | | Prossima data di messa in onda | Estratta da una pagina di palinsesto | Varia, vedi la documentazione | `next_episode_to_air`, null quando non è programmato nulla | | Stato della serie | Testo libero in una pagina | Varia, vedi la documentazione | Stringa `status` e flag `in_production` | | In onda questa settimana | Fare scraping di un palinsesto | Varia, vedi la documentazione | `/3/tv/on_the_air` e `/3/tv/airing_today` | | Lingue | Quelle offerte dalla pagina | Varia | 14, scelte con `language` | | Condizioni di accesso | Valgono le condizioni del sito | Piano gratuito con condizioni d'uso | A pagamento, prepagato, nessun piano gratuito | ## Prezzi Paga una volta per 1, 3, 6, 12 o 24 mesi. I periodi più lunghi hanno uno sconto del 10, 20, 30 o 40 per cento, e nulla si rinnova automaticamente. Ogni piano dà accesso a tutti i dati delle serie TV, con 20, 40 o 120 richieste al minuto come unica differenza. Vedi i [prezzi](https://amodb.dev/it/pricing/), crea una chiave, e la tua prima chiamata di serie costa una richiesta. ## Domande e risposte ### Come capisco se una serie TV è ancora in onda? Leggi status su /3/tv/{id}. Returning Series significa che sono attesi altri episodi, mentre Ended e Canceled significano che non ce ne saranno. Il campo next_episode_to_air contiene il prossimo episodio programmato e vale null quando non è programmato nulla. ### Posso recuperare tutti gli episodi di una serie con una sola richiesta? Una stagione per chiamata. GET /3/tv/{id}/season/{n} restituisce tutti gli episodi di quella stagione in un array episodes, quindi una serie di cinque stagioni richiede cinque chiamate di stagione più una chiamata di serie. ### Cosa ottengo per un'emittente? L'array networks di una serie elenca id, name, logo_path e origin_country. GET /3/network/{id} aggiunge i dettagli, e with_networks in /3/discover/tv elenca le serie di un'emittente. ### Posso elencare le serie in onda oggi? Sì. /3/tv/airing_today elenca le serie con un episodio in onda oggi e /3/tv/on_the_air copre i prossimi 7 giorni. Entrambi sono paginati, accettano language e restano 30 minuti nella cache edge. ### C'è un piano gratuito per l'API delle serie TV? Nessun piano gratuito e nessuna prova. Paghi in anticipo 1, 3, 6, 12 o 24 mesi e nulla si rinnova da solo. Ogni piano restituisce tutti i dati, e i piani differiscono solo per le richieste al minuto. ## 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 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 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. - [Società ed emittenti](https://amodb.dev/it/companies-networks/): Cerca case di produzione ed emittenti TV con i percorsi TMDB v3. Leggi nome, paese e logo per ID, poi filtra discover per ID di società o emittente. - [Tendenze e endpoint delle liste](https://amodb.dev/it/trending-lists/): API tendenze con percorsi TMDB v3: classifiche giorno e settimana, più liste di film e serie in sala, popolari, più votati e in arrivo, cache di 30 minuti. - [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-show-api/