API seriali: seriale, sezony i odcinki

API seriali ze statusem, sezonami i następnym odcinkiem

GET /3/tv/{series_id} zwraca serial z jego status, networks, listą seasons, last_episode_to_air i next_episode_to_air. Endpointy sezonów i odcinków dodają daty emisji, czas trwania i kadry. amodb to niezależne API mówiące protokołem TMDB v3, więc klient napisany dla TMDB działa po zmianie bazowego URL na https://api.amodb.dev/3.

Co dostajesz:

• Rekordy seriali z liczbą sezonów i odcinków oraz datami pierwszej i ostatniej emisji.
• Ciąg status i flagę in_production.
• Sieci telewizyjne z ID, logami i krajem pochodzenia.
• Jedno wywołanie na sezon, zwracające wszystkie odcinki tego sezonu.
• Listy seriali emitowanych dziś lub w ciągu następnych 7 dni.

Jakie dane dostajesz

Pełne listy pól są na stronach seriale oraz sezony i odcinki.

Start w 3 krokach

1. Otwórz cennik i wybierz plan z potrzebnym tempem żądań: 20, 40 lub 120 na minutę.
2. Utwórz klucz API w panelu konta.
3. Wyślij GET /3/tv/{series_id} z Authorization: Bearer YOUR_API_KEY albo dodaj api_key jako parametr zapytania.

Przykładowe żądanie

Skrypt odczytuje Breaking Bad (ID serialu 1396), wypisuje jego status i następny odcinek, a potem wypisuje sezon 1. Zapisz go jako check.mjs i uruchom w Node 18 lub nowszym.

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

Przycięta odpowiedź serialu dla language=en-US. Zostały tylko niektóre pola, a seasons pokazuje pierwsze 2 z 6 pozycji. Niektóre nazwy w tych danych nie podążają za language: nazwa sezonu 0 jest po chińsku, a name wewnątrz last_episode_to_air po hebrajsku.

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

Odczyt statusu i następnego odcinka

Ciąg status mówi, jak oznaczyć serial. next_episode_to_air jest obiektem tylko wtedy, gdy odcinek jest zaplanowany, więc ma wartość null między sezonami i po zakończeniu. Zanim pokażesz „zakończony”, sprawdź status.

Pola wewnątrz next_episode_to_air i last_episode_to_air: air_date, season_number, episode_number, episode_type, id, show_id, name, overview, runtime i still_path. Ciąg status może być też pusty w kilku tytułach, więc miej gotową neutralną etykietę.

Szczegóły są w cache na edge przez 6 godzin, więc pytanie o ten sam serial częściej niż cztery razy dziennie zwraca tę samą treść. Sprawdzaj obserwowane seriale raz lub dwa razy dziennie i odświeżaj ten, który użytkownik otwiera.

Sezony, odcinki i co jest w emisji

Sezon 0, jeśli serial go ma, zawiera odcinki specjalne. Zwykłe sezony zaczynają się od 1.

Listy i wyniki discover są w cache przez 30 minut, więc jedno żądanie na pół godziny wystarcza do plakietki „wkrótce w emisji”. Porównaj zwrócone ID z serialami, które obserwują twoi użytkownicy. Szczegóły sezonów i odcinków omawia strona przewodnik po odcinkach.

Budowanie listy obserwowanych z odliczaniem

Ekran „seriale, które obserwuję” potrzebuje jednego zapisanego ID na serial i małego codziennego zadania.

1. Zapisz id serialu, gdy użytkownik zacznie go obserwować.
2. Raz dziennie wywołaj /3/tv/{series_id} dla każdego obserwowanego ID i zapisz status, next_episode_to_air i last_air_date.
3. Gdy next_episode_to_air jest obiektem, pokaż air_date jako datę. Nie niesie pory dnia ani strefy czasowej, więc nie odliczaj co do minuty.
4. Gdy ma wartość null, a status to Returning Series, pokaż „nowy sezon nie jest zaplanowany”.
5. Wywołanie sezonu pobieraj tylko wtedy, gdy użytkownik otwiera serial, bo to największa odpowiedź.

404 z status_code 34 oznacza nieznane ID, a 429 oznacza przekroczenie liczby żądań na minutę: poczekaj Retry-After sekund. Przy 200 obserwowanych serialach jeden dzienny przebieg to 200 żądań, około dziesięciu minut przy 20 żądaniach na minutę. Zobacz limity żądań i błędy.

Jak wypada w porównaniu

Cennik

Płacisz raz za 1, 3, 6, 12 lub 24 miesiące. Dłuższe okresy mają zniżkę 10, 20, 30 lub 40 procent, a nic nie odnawia się automatycznie. Każdy plan dostaje wszystkie dane seriali, jedyną różnicą jest 20, 40 lub 120 żądań na minutę. Zobacz cennik, utwórz klucz, a pierwsze wywołanie serialu kosztuje jedno żądanie.