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.

Vedi i piani Leggi la guida rapida

Richiesta

curl JavaScript

bashjs

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"

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}`);
}

Risposta 200

{
  "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,

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 e stagioni ed episodi.

Parti in 3 passaggi

Apri la pagina dei prezzi e scegli il piano con la frequenza di richieste che ti serve: 20, 40 o 120 al minuto.
Crea una chiave API nella dashboard del tuo account.
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.

curl JavaScript

bashjs

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"

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.

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.

Salva l'id della serie quando un utente la segue.
Una volta al giorno chiama /3/tv/{series_id} per ogni ID seguito e salva status, next_episode_to_air e last_air_date.
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.
Quando è null e status è Returning Series, mostra «nuova stagione non programmata».
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 ed errori.

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, 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.

Aggiornato il 18 ott 2026

Vedi in Markdown