# 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/be/tv-series/) і [сезоны і эпізоды](https://amodb.dev/be/tv-seasons-episodes/). ## Пачніце за 3 крокі 1. Адкрыйце [цэны](https://amodb.dev/be/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` таксама можа быць пустым у некалькіх назваў, таму трымайце напагатове нейтральны подпіс. Дэталі кэшуюцца на edge на 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/be/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/be/rate-limits/) і [памылкі](https://amodb.dev/be/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/be/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/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду. - [API сезонаў і эпізодаў серыялаў](https://amodb.dev/be/tv-seasons-episodes/): API сезонаў і эпізодаў з тымі ж шляхамі і JSON, што ў TMDB v3. Чытайце сезон з усімі эпізодамі або адзін эпізод з датай эфіру, працягласцю і кадрам. - [API даведніка па эпізодах](https://amodb.dev/be/episode-guide-api/): API даведніка па эпізодах з эндпоінтамі сезонаў і эпізодаў TMDB v3: назвы, даты эфіру, працягласць, кадры і спісы груп эпізодаў для любога серыяла, на 14 мовах. - [Кампаніі і тэлеканалы](https://amodb.dev/be/companies-networks/): Шукайце кінакампаніі і тэлеканалы па шляхах TMDB v3. Чытайце назву, краіну і лагатып па id, потым фільтруйце discover па id кампаніі або тэлеканала. - [Эндпоінты трэндаў і спісаў](https://amodb.dev/be/trending-lists/): API трэндавых фільмаў з шляхамі TMDB v3: чарты за дзень і тыдзень, спісы зараз у пракаце, папулярных, лепшых і хутка ў пракаце, кэш 30 хвілін. - [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны. Абноўлена: 2026-10-18. Source: https://amodb.dev/be/tv-show-api/