# Альтернатива TheTVDB API

> TheTVDB зосереджений на серіалах і має кілька порядків епізодів: ефірний, DVD та абсолютний. amodb покриває серіали, фільми й персони одним ключем та одним запитом зіставляє TVDB id зі своїм id. Він показує групи епізодів шоу, але не їхній вміст, тож альтернативна нумерація лишається на боці TheTVDB.

## Що обрати для серіального проєкту

TheTVDB зосереджений на серіалах і зберігає для шоу кілька порядків епізодів, зокрема ефірний, DVD та абсолютний, а доступ надає за моделлю ключа API. Перш ніж планувати комерційний продукт, перегляньте їхню документацію щодо ліцензування. Обирайте amodb, коли вам потрібні серіали, фільми й персони з одним ключем, шляхи TMDB v3 та 14 мов. Обирайте TheTVDB, якщо в центрі вашого застосунку точна альтернативна нумерація, адже amodb показує групи епізодів шоу, але не віддає їхній вміст.

## Як дані про серіали зіставляються між двома сервісами

Поняття збігаються, але назви різні. Ця таблиця охоплює те, що зазвичай читає застосунок про серіали.

| Потреба                          | Підхід TheTVDB                     | Виклик amodb                                               |
| -------------------------------- | ---------------------------------- | ---------------------------------------------------------- |
| Один серіал                      | Запис серіалу за TVDB id           | `GET /3/tv/1396`, після пошуку за `tvdb_id`                |
| Список сезонів                   | Дивіться їхню документацію         | масив `seasons` у деталях серіалу                          |
| Один сезон з епізодами           | Дивіться їхню документацію         | `GET /3/tv/1396/season/1`                                  |
| Один епізод                      | Дивіться їхню документацію         | `GET /3/tv/1396/season/1/episode/1`                        |
| Які порядки існують              | Ефірний, DVD та абсолютний порядки | `GET /3/tv/1396/episode_groups`                            |
| Епізоди всередині одного порядку | Дивіться їхню документацію         | Не пропонується, `/3/tv/episode_group/{id}` відповідає 404 |
| Наступний епізод в ефірі         | Дивіться їхню документацію         | `next_episode_to_air` у деталях серіалу                    |

Поля епізодів мають назви з TMDB: `air_date`, `episode_number`, `season_number`, `runtime` і `still_path`. Усі `external_ids` сезонів та епізодів дорівнюють null, тож TVDB id окремого сезону чи епізоду з amodb прочитати не можна. Натомість зіставляйте за `season_number` і `episode_number`. Подробиці на сторінці [сезони та серії](https://amodb.dev/uk/tv-seasons-episodes/).

## Що повертає список груп епізодів

Виклик зі списком показує, які порядки існують для серіалу. Самих епізодів усередині них він не повертає.

| Поле            | Значення                                      |
| --------------- | --------------------------------------------- |
| `id`            | Id групи, рядок                               |
| `name`          | Назва порядку, наприклад `DVD / PVOD`         |
| `description`   | Текст із джерела, часто порожній              |
| `type`          | Число, що вказує на вид порядку               |
| `episode_count` | Кількість епізодів у порядку                  |
| `group_count`   | Кількість блоків у порядку, наприклад сезонів |
| `network`       | Об'єкт із телемережею або null                |

Ось справжня відповідь для Breaking Bad.

```json
{
  "id": 1396,
  "results": [
    {
      "description": "Seasons grouped as they appear on DVD, as well as paid video-on-demand services, such as Prime Video and YouTube.",
      "episode_count": 62,
      "group_count": 6,
      "id": "69f50757054263b7bc87e32a",
      "name": "DVD / PVOD",
      "network": null,
      "type": 3
    }
  ]
}
```

Одні шоу повертають один ефірний порядок, інші кілька, а деякі повертають порожній масив `results`. Перевірте шоу, які вас цікавлять. Оскільки вміст групи не віддається, застосунок, якому потрібен DVD-номер чи абсолютний номер кожного епізоду, не отримає його з amodb.

## Порівняння можливостей

| Можливість              | TheTVDB                                                            | amodb                                                     |
| ----------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
| Модель цін              | Модель ключа API, умови ліцензування дивіться в їхній документації | Передплачені періоди від 1 до 24 місяців                  |
| Безкоштовний тариф      | Дивіться їхню документацію                                         | Немає, пробного періоду теж немає                         |
| Автентифікація          | Ключ API, порядок дій дивіться в їхній документації                | `api_key` або заголовок Bearer                            |
| Формат відповіді        | JSON, дивіться їхню документацію                                   | JSON у формі TMDB v3                                      |
| Мови                    | Дивіться їхню документацію                                         | 14 мов інтерфейсу                                         |
| Фільми                  | Дивіться їхню документацію                                         | Так                                                       |
| Серіали                 | Так, це його основний фокус                                        | Так, із сезонами та серіями                               |
| Персони                 | Дивіться їхню документацію                                         | Так                                                       |
| Зображення              | Дивіться їхню документацію                                         | `img.amodb.dev`, ключ не потрібен                         |
| Рейтинги                | Дивіться їхню документацію                                         | IMDb та ще чотири джерела, де вони відомі                 |
| Ліміт запитів           | Дивіться їхню документацію                                         | 20, 40 або 120 на хвилину на ключ                         |
| Комерційне використання | Умови ліцензування дивіться в їхній документації                   | Платні тарифи, див. [ціни](https://amodb.dev/uk/pricing/) |
| Сумісність              | Власний API                                                        | Читання TMDB v3 та OMDb                                   |

## Чим відрізняється amodb

- **Один ключ на весь каталог.** Серіал, його акторський склад, трейлери та фільм зі спільним актором використовують один базовий URL і один ліміт.
- **Рейтинги поруч із довідником епізодів.** `append_to_response=ratings` у деталях серіалу додає IMDb та інші оцінки одним запитом.
- **Прості заголовки для контролю темпу.** `X-RateLimit-Remaining` і `X-RateLimit-Reset` показують завданню синхронізації, скільки запитів лишилося у вікні на 60 секунд.
- **Збережені оригінальні назви.** Серіал зберігає `original_name`, тоді як `name` відповідає вашому `language`, що допомагає показати рідну назву.

## Коли TheTVDB підходить краще

- **Порядок і є продуктом.** Якщо ваші користувачі сперечаються про DVD проти ефірного проти абсолютного порядку, TheTVDB розглядає це як ядро своєї моделі. amodb називає порядки шоу, але не повертає їхні епізоди, а набір груп залежить від шоу.
- **Наявні інтеграції.** Якщо ваш конвеєр уже зберігає id TheTVDB і читає його порядки, залиште цю частину й додайте amodb для решти даних.
- **Фокус на серіалах.** Якщо ви ніколи не показуєте фільми чи персон, джерело, створене навколо серіалів, простіше опанувати.

## Міграція на amodb

Один раз зіставте збережені TVDB id. Далі для кожного виклику використовуйте id amodb. Ендпоінт find розпізнає лише id серіалів. Його масиви `tv_season_results` і `tv_episode_results` завжди порожні, тож сезони та епізоди зіставляйте за номером.

```js
const key = process.env.AMODB_KEY;
const headers = { Authorization: `Bearer ${key}` };
const base = 'https://api.amodb.dev/3';

async function getJson(path) {
  const res = await fetch(`${base}${path}`, { headers });
  if (!res.ok) throw new Error(`${path} returned ${res.status}`);
  return res.json();
}

const found = await getJson('/find/81189?external_source=tvdb_id');
const show = found.tv_results[0];
console.log(show.id, show.name);

const groups = await getJson(`/tv/${show.id}/episode_groups`);
for (const g of groups.results) {
  console.log(g.name, g.type, g.episode_count);
}
```

Перший запит повертає Breaking Bad з id 1396. Другий перелічує порядки, що існують для цього шоу, разом з їхніми розмірами. Щоб порівняти нумерацію з тим, що ви зберігаєте зараз, читайте ефірний порядок із `/tv/{id}/season/{n}`, а будь-який альтернативний порядок залишайте на боці TheTVDB. Зробіть цю перевірку на десяти найпопулярніших шоу, перш ніж переносити решту.

Кожен виклик рахується як один запит у вікні на 60 секунд, а відповідь 429 містить `Retry-After`. Див. [пошук за зовнішнім ID](https://amodb.dev/uk/find-by-external-id/) та [ліміти запитів](https://amodb.dev/uk/rate-limits/).

## Ціни

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

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

### Чи можна перетворити TVDB id на id amodb?

Так. Викличте /3/find/81189 з external_source=tvdb_id. Масив tv_results містить відповідний серіал, тож Breaking Bad повертається з id 1396. Збережіть пару й надалі користуйтеся числовим id. Працює й у зворотний бік: /3/tv/1396/external_ids повертає tvdb_id.

### Чи підтримує amodb порядок епізодів DVD та абсолютний?

Лише частково. GET /3/tv/{id}/episode_groups показує групи шоу з name, type, episode_count і group_count. Вміст групи не віддається, а /3/tv/episode_group/{id} відповідає 404. Ви бачите, що порядок DVD існує, але прочитати його нумерацію не можете.

### Чи безкоштовний TheTVDB?

TheTVDB працює за моделлю ключа API, а умови ліцензування визначає сам TheTVDB. Актуальну ліцензію та можливу плату дивіться в їхній документації. amodb це платний API з передплатою, без безкоштовного тарифу.

### Чи отримаю я ще й дані про фільми?

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

### Як дізнатися, коли вийде наступна серія?

Деталі серіалу містять next_episode_to_air і last_episode_to_air, у кожному є season_number, episode_number та air_date. Для завершеного шоу наступна серія дорівнює null. Деталі кешуються на edge на 6 годин, тож опитуйте їх щонайбільше кілька разів на день.

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

- [API сезонів і серій серіалів](https://amodb.dev/uk/tv-seasons-episodes/): API сезонів і серій серіалів з тими самими шляхами та JSON, що в TMDB v3. Читайте сезон з усіма серіями або одну серію з датою виходу, тривалістю та кадром.
- [Пошук за зовнішнім ID](https://amodb.dev/uk/find-by-external-id/): Знайдіть фільм, серіал чи персону за id IMDb, TVDB, Wikidata або Kinopoisk через find TMDB, а також прочитайте зовнішні id і факти Wikidata про проєкт.
- [API довідника серій](https://amodb.dev/uk/episode-guide-api/): API довідника серій на ендпоінтах сезонів і серій TMDB v3: назви, дати виходу, тривалість, кадри та списки груп серій для будь-якого серіалу, 14 мов.
- [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги.
- [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини.
- [Ліміти запитів](https://amodb.dev/uk/rate-limits/): amodb обмежує кожен ключ запитами на хвилину в ковзному вікні 60 секунд: 20, 40 або 120 за тарифом. Читайте заголовки ліміту й обробляйте 429 із Retry-After.

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