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.

Vedi i piani Leggi la guida rapida

Richiesta

curl Go

bashgo

curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

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 200

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

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

Scegli un piano nella pagina dei prezzi. Tutti i piani restituiscono gli stessi dati sugli episodi, cambia solo la frequenza delle richieste.
Crea una chiave nella dashboard del tuo account e salvala in una variabile d'ambiente.
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.

curl Go

bashgo

curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

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.

JavaScript

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

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 e crediti.

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.

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.

Aggiornato il 18 ott 2026

Vedi in Markdown