# Альтэрнатыва TheTVDB API

> TheTVDB арыентаваны на серыялы і прапануе некалькі парадкаў эпізодаў, такіх як эфірны, DVD і абсалютны. amodb ахоплівае серыялы, фільмы і персон з адным ключом і супастаўляе id TVDB са сваім id адным выклікам. Ён пералічвае групы эпізодаў серыяла, але не іх змест, таму альтэрнатыўная нумарацыя застаецца ў TheTVDB.

## Што падыходзіць для праекта пра серыялы

TheTVDB арыентаваны на серыялы і трымае для серыяла некалькі парадкаў эпізодаў, уключна з эфірным, DVD і абсалютным, па мадэлі ключа API. Перад тым як планаваць камерцыйны прадукт, праверце ліцэнзаванне ў іх дакументацыі. Абірайце amodb, калі вам патрэбны серыялы, фільмы і персоны з аднаго ключа, шляхі TMDB v3 і 14 моў. Абірайце TheTVDB, калі дакладная альтэрнатыўная нумарацыя ёсць цэнтрам вашай праграмы, бо amodb пералічвае групы эпізодаў серыяла, але не аддае тое, што ўнутры іх.

## Як даныя пра серыялы супастаўляюцца паміж імі

Паняцці супадаюць, але назвы адрозніваюцца. Гэтая табліца ахоплівае тое, што звычайна чытае праграма пра серыялы.

| Што трэба                     | Падыход TheTVDB                 | Выклік amodb                                            |
| ----------------------------- | ------------------------------- | ------------------------------------------------------- |
| Адзін серыял                  | Запіс серыяла па id TVDB        | `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, таму id TVDB асобнага сезона або эпізода з amodb прачытаць нельга. Злучайце па `season_number` і `episode_number`. Падрабязнасці на старонцы [сезоны і эпізоды](https://amodb.dev/be/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/be/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

Адзін раз супастаўце захаваныя id TVDB. Пасля гэтага выкарыстоўвайце 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`. Гл. [пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/) і [ліміты запытаў](https://amodb.dev/be/rate-limits/).

## Цэны

amodb працуе з аплатай наперад і без аўтапрадаўжэння. Абярыце 1, 3, 6, 12 або 24 месяцы і адзін з трох планаў на 20, 40 або 120 запытаў у хвіліну. Доўгія перыяды даюць зніжку 10, 20, 30 або 40 працэнтаў, і кожны план дае ўсе даныя. Бясплатнага тарыфа няма. Сумы ёсць на старонцы [цэны](https://amodb.dev/be/pricing/).

## Пытанні і адказы

### Ці можна пераўтварыць id TVDB у 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/be/tv-seasons-episodes/): API сезонаў і эпізодаў з тымі ж шляхамі і JSON, што ў TMDB v3. Чытайце сезон з усімі эпізодамі або адзін эпізод з датай эфіру, працягласцю і кадрам.
- [Пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/): Шукайце фільм, серыял або персону па IMDb, TVDB, Wikidata ці Kinopoisk id праз эндпоінт find TMDB і чытайце вонкавыя id і факты Wikidata для назвы.
- [API даведніка па эпізодах](https://amodb.dev/be/episode-guide-api/): API даведніка па эпізодах з эндпоінтамі сезонаў і эпізодаў TMDB v3: назвы, даты эфіру, працягласць, кадры і спісы груп эпізодаў для любога серыяла, на 14 мовах.
- [API серыялаў](https://amodb.dev/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду.
- [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны.
- [Ліміты запытаў](https://amodb.dev/be/rate-limits/): amodb абмяжоўвае ключ па запытах у хвіліну ў слізгальным акне 60 секунд: 20, 40 або 120 па плане. Чытайце загалоўкі лімітаў і апрацоўвайце 429 праз Retry-After.

Абноўлена: 2026-10-18. Source: https://amodb.dev/be/thetvdb-api-alternative/