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

> API серіалів повертає серіал на GET /3/tv/{series_id} зі статусом, телемережами, списком сезонів і next_episode_to_air. Ендпоінти сезонів і серій додають дати виходу, тривалість і кадри. JSON збігається з TMDB v3, 14 мов, передплачені тарифи на 20, 40 або 120 запитів на хвилину.

## 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 днів.

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

| Вам потрібно             | Виклик                                                                  | Ключові поля                                                                                  |
| ------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Запис серіалу            | `GET /3/tv/{series_id}`                                                 | `name`, `original_name`, `status`, `in_production`, `number_of_seasons`, `number_of_episodes` |
| Наступна й остання серія | той самий виклик                                                        | `next_episode_to_air`, `last_episode_to_air`                                                  |
| Один сезон               | `GET /3/tv/{series_id}/season/{season_number}`                          | `episodes`, `air_date`, `poster_path`                                                         |
| Одна серія               | `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` | `name`, `overview`, `runtime`, `still_path`, `air_date`                                       |
| Телемережа               | `GET /3/network/{network_id}`                                           | `name`, `headquarters`, `origin_country`                                                      |

Повні списки полів дивіться на сторінках [серіали](https://amodb.dev/uk/tv-series/) і [сезони та серії](https://amodb.dev/uk/tv-seasons-episodes/).

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

1. Відкрийте [ціни](https://amodb.dev/uk/pricing/) і виберіть тариф із потрібною кількістю запитів: 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 або новішій версії.

```bash
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"
```

```js
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` івритом.

```json
{
  "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`, перш ніж показувати «завершено».

| `status`         | Значення                             | Що показувати                                                         |
| ---------------- | ------------------------------------ | --------------------------------------------------------------------- |
| Returning Series | Очікуються нові серії                | Дату виходу наступної серії, якщо об'єкт існує, інакше «повертається» |
| In Production    | Знімається, ще не в ефірі            | «У виробництві»                                                       |
| Planned          | Лише анонсовано                      | «Заплановано»                                                         |
| Pilot            | Існує лише пілот                     | «Пілот»                                                               |
| Ended            | Показ завершено                      | «Завершено» і `last_air_date`                                         |
| Canceled         | Зупинено до запланованого завершення | «Скасовано»                                                           |

Поля всередині `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.

| Виклик                                         | Що повертає                                           | Параметри                                         |
| ---------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------- |
| `GET /3/tv/{series_id}/season/{season_number}` | Запис сезону з масивом `episodes`                     | `language`, `append_to_response`                  |
| `GET /3/tv/airing_today`                       | Серіали із серією, що виходить сьогодні               | `page`, `language`                                |
| `GET /3/tv/on_the_air`                         | Серіали, що виходять протягом найближчого тижня       | `page`, `language`                                |
| `GET /3/discover/tv`                           | Серіали, відфільтровані за телемережею, статусом тощо | `with_networks`, `with_status`, `sort_by`, `page` |

Списки й результати discover кешуються на 30 хвилин, тож одного запиту на пів години досить для позначки «скоро в ефірі». Зіставте повернуті id із серіалами, які відстежують ваші користувачі. Подробиці про сезони й серії описано на сторінці [довідник серій](https://amodb.dev/uk/episode-guide-api/).

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

Екран «серіали, які я відстежую» потребує одного збереженого 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 запитів на хвилину. Дивіться [ліміти запитів](https://amodb.dev/uk/rate-limits/) і [помилки](https://amodb.dev/uk/errors/).

## Порівняння

| Можливість                | Скрапінг сторінок власноруч       | Безкоштовний API метаданих                | amodb                                                   |
| ------------------------- | --------------------------------- | ----------------------------------------- | ------------------------------------------------------- |
| Структура сезонів і серій | Відновлюється з макетів сторінок  | По-різному, дивіться документацію         | Виклик сезону з масивом `episodes`                      |
| Дата наступної серії      | Розбирається зі сторінки розкладу | По-різному, дивіться документацію         | `next_episode_to_air`, null, коли нічого не заплановано |
| Статус серіалу            | Вільний текст на сторінці         | По-різному, дивіться документацію         | Рядок `status` і прапорець `in_production`              |
| Що виходить цього тижня   | Скрапінг розкладу                 | По-різному, дивіться документацію         | `/3/tv/on_the_air` і `/3/tv/airing_today`               |
| Мови                      | Те, що пропонує сторінка          | По-різному                                | 14, вибираються через `language`                        |
| Умови доступу             | Діють умови сайту                 | Безкоштовний тариф з умовами використання | Платно, передплата, без безкоштовного тарифу            |

## Ціни

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

## Запитання й відповіді

### Як дізнатися, чи серіал досі виходить?

Прочитайте status на /3/tv/{id}. Returning Series означає, що очікуються нові серії, а Ended і Canceled означають, що їх не буде. Поле next_episode_to_air містить наступну заплановану серію й дорівнює null, якщо нічого не заплановано.

### Чи можна отримати всі серії серіалу одним запитом?

Один сезон за виклик. GET /3/tv/{id}/season/{n} повертає всі серії сезону в масиві episodes, тож серіал із п'ятьма сезонами потребує п'яти викликів сезонів плюс одного виклику серіалу.

### Що я отримаю для телемережі?

Масив networks у серіалу перелічує id, name, logo_path і origin_country. GET /3/network/{id} додає подробиці, а with_networks у /3/discover/tv перелічує серіали однієї телемережі.

### Чи можна вивести серіали, що виходять сьогодні?

Так. /3/tv/airing_today перелічує серіали із серією, що виходить сьогодні, а /3/tv/on_the_air охоплює наступні 7 днів. Обидва розбиті на сторінки, приймають language і лежать в edge-кеші 30 хвилин.

### Чи є безкоштовний тариф для API серіалів?

Безкоштовного тарифу й пробного періоду немає. Ви передплачуєте 1, 3, 6, 12 або 24 місяці, і нічого не поновлюється автоматично. Кожен тариф повертає всі дані, а тарифи відрізняються лише кількістю запитів на хвилину.

## Пов'язані сторінки

- [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги.
- [API сезонів і серій серіалів](https://amodb.dev/uk/tv-seasons-episodes/): API сезонів і серій серіалів з тими самими шляхами та JSON, що в TMDB v3. Читайте сезон з усіма серіями або одну серію з датою виходу, тривалістю та кадром.
- [API довідника серій](https://amodb.dev/uk/episode-guide-api/): API довідника серій на ендпоінтах сезонів і серій TMDB v3: назви, дати виходу, тривалість, кадри та списки груп серій для будь-якого серіалу, 14 мов.
- [Компанії та телемережі](https://amodb.dev/uk/companies-networks/): Дані про кінокомпанії та телемережі зі шляхами TMDB v3. Отримайте назву, країну й логотип за id, а потім відфільтруйте discover за id компанії чи мережі.
- [Ендпоінти трендів і списків](https://amodb.dev/uk/trending-lists/): API трендів фільмів зі шляхами TMDB v3: чарти за день і тиждень, а також списки в прокаті, популярних, найкращих і майбутніх фільмів та серіалів, кеш 30 хвилин.
- [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини.

Оновлено: 2026-10-18. Source: https://amodb.dev/uk/tv-show-api/