API серіалів з даними про сезони та серії

API серіалів зі статусом, сезонами та наступною серією

GET /3/tv/{series_id} повертає серіал із його status, networks, списком seasons, last_episode_to_air і next_episode_to_air. Ендпоінти сезонів і серій додають дати виходу, тривалість і кадри. amodb це незалежний API, що говорить протоколом TMDB v3, тож клієнт, написаний для TMDB, працює після зміни базового URL на https://api.amodb.dev/3.

Що ви отримуєте:

• Записи серіалів із кількістю сезонів і серій, а також датами першого й останнього виходу.
• Рядок status і прапорець in_production.
• Телемережі з id, логотипами та країною походження.
• Один виклик на сезон, що повертає всі серії цього сезону.
• Списки серіалів, які виходять в ефір сьогодні або протягом наступних 7 днів.

Які дані ви отримуєте

Повні списки полів дивіться на сторінках серіали і сезони та серії.

Почніть за 3 кроки

1. Відкрийте ціни і виберіть тариф із потрібною кількістю запитів: 20, 40 або 120 на хвилину.
2. Створіть ключ API у кабінеті акаунта.
3. Надішліть GET /3/tv/{series_id} із Authorization: Bearer YOUR_API_KEY або додайте api_key як параметр запиту.

Приклад запиту

Скрипт читає Breaking Bad (id серіалу 1396), виводить його статус і наступну серію, а потім перелічує сезон 1. Збережіть його як check.mjs і запустіть у Node 18 або новішій версії.

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

Скорочена відповідь про серіал для language=en-US. Збережено лише деякі поля, а seasons показує перші 2 із 6 записів. Деякі назви в цих даних не відповідають language: назва сезону 0 китайською, а name усередині last_episode_to_air івритом.

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

Як читати статус і наступну серію

Рядок status підказує, як позначити серіал. next_episode_to_air є об'єктом лише доти, доки серію заплановано, тож між сезонами він null так само, як і після завершення. Перевіряйте status, перш ніж показувати «завершено».

Поля всередині next_episode_to_air і last_episode_to_air: air_date, season_number, episode_number, episode_type, id, show_id, name, overview, runtime і still_path. Рядок status у кількох тайтлів може бути й порожнім, тож тримайте напоготові нейтральну позначку.

Деталі кешуються на краю мережі на 6 годин, тож якщо запитувати той самий серіал частіше ніж чотири рази на добу, повертається те саме тіло відповіді. Опитуйте відстежувані серіали раз-два на добу й оновлюйте той, який відкриває користувач.

Сезони, серії та що в ефірі

Сезон 0, якщо він є в серіалу, містить спецвипуски. Звичайні сезони починаються з 1.

Списки й результати discover кешуються на 30 хвилин, тож одного запиту на пів години досить для позначки «скоро в ефірі». Зіставте повернуті id із серіалами, які відстежують ваші користувачі. Подробиці про сезони й серії описано на сторінці довідник серій.

Список відстежуваних серіалів із зворотним відліком

Екран «серіали, які я відстежую» потребує одного збереженого id на серіал і невеликого щоденного завдання.

1. Збережіть id серіалу, коли користувач починає його відстежувати.
2. Раз на добу викликайте /3/tv/{series_id} для кожного відстежуваного id і зберігайте status, next_episode_to_air і last_air_date.
3. Коли next_episode_to_air є об'єктом, покажіть air_date як дату. Вона не містить ні часу доби, ні часового поясу, тож не відлічуйте до хвилини.
4. Коли він null, а status має значення Returning Series, покажіть «новий сезон не заплановано».
5. Викликайте сезон лише тоді, коли користувач відкриває серіал, адже це найбільша відповідь.

404 із status_code 34 означає, що id невідомий, а 429 означає, що ви перевищили ліміт запитів на хвилину: зачекайте Retry-After секунд. Для 200 відстежуваних серіалів один щоденний прохід це 200 запитів, близько десяти хвилин за 20 запитів на хвилину. Дивіться ліміти запитів і помилки.

Порівняння

Ціни

Заплатіть один раз за 1, 3, 6, 12 або 24 місяці. Довші періоди дають знижку 10, 20, 30 або 40 відсотків, і ніщо не поновлюється автоматично. Кожен тариф отримує всі дані про серіали, а єдина відмінність це 20, 40 або 120 запитів на хвилину. Дивіться ціни, створіть ключ, і ваш перший виклик серіалу коштуватиме один запит.