API seriálů pro seriály, sezóny a epizody

API seriálů se stavem, sezónami a další epizodou

GET /3/tv/{series_id} vrací seriál s jeho status, networks, seznamem seasons, last_episode_to_air a next_episode_to_air. Endpointy sezón a epizod doplňují data vysílání, délky a záběry. amodb je nezávislé API mluvící protokolem TMDB v3, takže klient napsaný pro TMDB funguje po změně základní URL na https://api.amodb.dev/3.

Co dostanete:

• Záznamy seriálů s počtem sezón a epizod a daty prvního a posledního vysílání.
• Řetězec status a příznak in_production.
• Televizní sítě s ID, logy a zemí původu.
• Jedno volání na sezónu, které vrací všechny epizody dané sezóny.
• Seznamy seriálů, které se vysílají dnes nebo během příštích 7 dní.

Jaká data dostanete

Úplné seznamy polí jsou na stránkách seriály a sezóny a epizody.

Začněte ve 3 krocích

1. Otevřete ceník a vyberte tarif s potřebnou rychlostí požadavků: 20, 40 nebo 120 za minutu.
2. Vytvořte klíč API v panelu účtu.
3. Pošlete GET /3/tv/{series_id} s Authorization: Bearer YOUR_API_KEY nebo přidejte api_key jako parametr dotazu.

Příklad požadavku

Skript přečte Breaking Bad (ID seriálu 1396), vypíše jeho stav a další epizodu a pak vypíše sezónu 1. Uložte jej jako check.mjs a spusťte v Node 18 nebo novějším.

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

Zkrácená odpověď seriálu pro language=en-US. Zůstala jen část polí a seasons ukazuje první 2 ze 6 položek. Některé názvy v těchto datech language nedodržují: název sezóny 0 je čínsky a name uvnitř last_episode_to_air je hebrejsky.

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

Čtení stavu a další epizody

Řetězec status říká, jak seriál označit. next_episode_to_air je objekt jen tehdy, když je epizoda naplánovaná, takže je null mezi sezónami i po skončení. Než zobrazíte „skončil“, otestujte status.

Pole uvnitř next_episode_to_air a last_episode_to_air: air_date, season_number, episode_number, episode_type, id, show_id, name, overview, runtime a still_path. Řetězec status může být u několika titulů také prázdný, mějte proto připravený neutrální popisek.

Detaily se na edge cachují 6 hodin, takže dotaz na stejný seriál více než čtyřikrát denně vrátí stejné tělo. Sledované seriály kontrolujte jednou nebo dvakrát denně a obnovujte ten, který uživatel otevře.

Sezóny, epizody a co se právě vysílá

Sezóna 0, pokud ji seriál má, obsahuje speciály. Běžné sezóny začínají od 1.

Seznamy a výsledky discover se cachují 30 minut, takže jeden požadavek za půl hodiny stačí pro odznak „brzy ve vysílání“. Vrácená ID porovnejte se seriály, které vaši uživatelé sledují. Detaily sezón a epizod pokrývá stránka průvodce epizodami.

Seznam sledovaných seriálů s odpočty

Obrazovka „seriály, které sleduji“ potřebuje jedno uložené ID na seriál a malou denní úlohu.

1. Uložte id seriálu, když ho uživatel začne sledovat.
2. Jednou denně zavolejte /3/tv/{series_id} pro každé sledované ID a uložte status, next_episode_to_air a last_air_date.
3. Když je next_episode_to_air objekt, zobrazte air_date jako datum. Nenese denní dobu ani časové pásmo, neodpočítávejte proto na minuty.
4. Když je null a status je Returning Series, zobrazte „nová sezóna není naplánována“.
5. Volání sezóny načtěte jen tehdy, když uživatel seriál otevře, protože je to největší odpověď.

404 se status_code 34 znamená neznámé ID a 429 znamená překročení počtu požadavků za minutu: počkejte Retry-After sekund. Při 200 sledovaných seriálech je jeden denní průchod 200 požadavků, asi deset minut při 20 požadavcích za minutu. Viz limity požadavků a chyby.

Jak si stojí v porovnání

Ceník

Platíte jednou za 1, 3, 6, 12 nebo 24 měsíců. U delších období je sleva 10, 20, 30 nebo 40 procent a nic se neobnovuje automaticky. Každý tarif dostane všechna data seriálů, jediný rozdíl je 20, 40 nebo 120 požadavků za minutu. Viz ceník, vytvořte klíč a první volání seriálu stojí jeden požadavek.