API sezoane și episoade TV

Obține un sezon

GET /3/tv/{series_id}/season/{season_number} întoarce un sezon și array-ul lui complet episodes într-un singur răspuns. Numerele de sezon încep de la 1, iar 0 este rezervat pentru episoadele speciale. Ia ID-ul serialului și numerele de sezon din fișa seriale TV.

Exemplul citește sezonul 1 din Breaking Bad. Codul afișează câte o linie pe episod.

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

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

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
$url = 'https://api.amodb.dev/3/tv/1396/season/1?language=en-US';
$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");
}
$season = json_decode($body, true);
foreach ($season['episodes'] as $ep) {
    printf("%02d %s %s\n", $ep['episode_number'], $ep['name'], $ep['air_date']);
}

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

• series_idcaleobligatoriu
  ID numeric de TV, de exemplu 1396.
• season_numbercaleobligatoriu
  Număr întreg de sezon. 0 întoarce episoadele speciale.
• api_keyinterogareuna dintre cele două
  Cheia ta. Folosește-o pe aceasta sau antetul Authorization: Bearer.
• languageinterogare
  Etichetă TMDB precum en-US sau fr-FR. Sunt servite 14 limbi de bază. Implicit en-US.
• append_to_responseinterogare
  Valori la nivel de sezon: credits, external_ids, images, videos. Alte nume sunt ignorate.

Câmpurile răspunsului

Exemplu de răspuns

GET /3/tv/1396/season/1?language=en-US. Sezonul are 7 episoade, deci episodes este tăiat la o intrare, iar array-urile crew și guest_stars ale acelei intrări sunt omise:

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

Fiecare episod din răspunsul de sezon poartă și array-urile crew și guest_stars, cu structura de intrare descrisă la credite. runtime poate fi null pentru un episod nedifuzat.

Obține un episod

GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number} întoarce un episod. Răspunsul de sezon conține deja fiecare episod cu crew și guest_stars, deci folosește acest endpoint ca să reîmprospătezi o singură înregistrare fără să reîncarci sezonul. Acceptă language și append_to_response cu credits, external_ids, images, translations și videos. O cerere precum /3/tv/1396/season/1/episode/1?append_to_response=credits costă o cerere.

Următorul și ultimul episod din fișa serialului

Endpoint-ul de serial întoarce next_episode_to_air și last_episode_to_air. Fiecare este un rezumat de episod cu câmpurile de mai sus, plus show_id și fără crew și guest_stars. Următorul este null pentru serialele încheiate și pentru cele care revin fără o dată confirmată. Exemplul citește South Park, un serial care revine.

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');

Pentru o numărătoare inversă, compară air_date cu data locală a spectatorului. Valoarea nu poartă ora zilei, deci arată o dată și nu o oră de ceas.

Sub-resurse de sezon și de episod

Căile de sezon și de episod au propriile sub-resurse. Câteva dintre ele întorc azi date goale.

Creditele de sezon și de episod sunt tratate la credite, iar cadrele la imagini. amodb nu oferă căile TMDB changes sau un endpoint pentru episoadele unui grup de episoade.

Erori

Vezi erori pentru formatul complet al corpului și limite de cereri pentru ferestre.

Note practice

• Sezoanele și episoadele sunt ținute în cache 6 ore. Recitește sezonul curent o dată sau de două ori pe zi cât timp se difuzează serialul.
• Un serial cu 10 sezoane cere 10 apeluri de sezon. Pe planul de 20 de cereri pe minut asta folosește jumătate din alocarea unui minut, iar o rulare repetată în 6 ore este servită din cache-ul la margine.
• Un episod nedifuzat poate avea air_date null, runtime null și overview gol. Afișează un substituent în loc să eșuezi.
• Cadrele sunt imagini late, nu postere. Cere w300 pentru liste și original doar când ai nevoie de o vizualizare la dimensiune completă.