# Эндпоінты трэндаў і спісаў > Эндпоінты трэндаў і спісаў вяртаюць ранжыраваныя старонкі фільмаў, серыялаў або персон. Выкарыстоўвайце GET /3/trending/{media_type}/{time_window} для чартаў за дзень і тыдзень, а таксама шляхі спісаў movie і tv для папулярных, лепшых, зараз у пракаце, хутка ў пракаце, сёння ў эфіры і ў эфіры. Кожная старонка змяшчае 20 вынікаў і кэшуецца на 30 хвілін. ## Эндпоінт `GET /3/trending/{media_type}/{time_window}` ```bash curl "https://api.amodb.dev/3/trending/movie/week?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Адказ: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/mBZKC8ActTlM4W3HEGI1Cl1RtO3.jpg", "genre_ids": [ 878, 9648, 28 ], "id": 1058424, "original_language": "ko", "original_title": "호프", "overview": "In the remote South Korean village of Hope Harbor, police chief Bum-seok and officer Sung-ae are called to investigate a mysterious creature wreaking havoc on the community. But all is not as it seems, and perceptions can be misleading. Wha...", "popularity": 368.4952, "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg", "release_date": "2026-07-15", "title": "Hope", "video": false, "vote_average": 6.9, "vote_count": 256, "media_type": "movie" }, { "adult": false, "backdrop_path": "/5YfPIIMzGBkIjHt3PTXBWyfBTGS.jpg", "genre_ids": [ 28, 14 ], "id": 1153576, "original_language": "en", "original_title": "Street Fighter", "overview": "In 1993, estranged Street Fighters Ryu and Ken Masters are thrown back into combat when the mysterious Chun-Li recruits them for the next World Warrior Tournament: a brutal clash of fists, fate, and fury. But behind this battle royale lies...", "popularity": 225.4202, "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg", "release_date": "2026-10-13", "title": "Street Fighter", "video": false, "vote_average": 6.365, "vote_count": 85, "media_type": "movie" }, { "adult": false, "backdrop_path": "/tanwf7KOwQ6dxZzehKsXkffIJOd.jpg", "genre_ids": [ 878, 28, 12 ], "id": 969681, "original_language": "en", "original_title": "Spider-Man: Brand New Day", "overview": "Fighting crime full-time as Spider-Man in a world that doesn't remember him—and the pressure of seeing his old friends move on without him—sparks a change in Peter Parker he may not have the power to control. But that transformation might a...", "popularity": 655.4447, "poster_path": "/bjiS5ipwxb9JFy3XRRN4OAilSeX.jpg", "release_date": "2026-07-29", "title": "Spider-Man: Brand New Day", "video": false, "vote_average": 8.469, "vote_count": 5725, "media_type": "movie" } ], "total_pages": 500, "total_results": 10000 } ``` ## Атрыманне трэндавых назваў `GET /3/trending/{media_type}/{time_window}` вяртае ранжыраваную старонку таго, што людзі глядзяць або шукаюць менавіта цяпер. `media_type` гэта `all`, `movie`, `tv` або `person`. `time_window` гэта `day` або `week`. Чарты за дзень хутка мяняюцца і пасуюць для стужкі «сёння ўвечары». Чарты за тыдзень стабільнейшыя і пасуюць для галоўнай старонкі. У прыкладзе запытваецца тыднёвы чарт фільмаў і друкуюцца першыя дзесяць назваў. ```bash curl -s "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const chart = await res.json(); for (const [i, m] of chart.results.slice(0, 10).entries()) { console.log(i + 1, m.title, m.release_date); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/trending/movie/week", params={"language": "en-US", "page": 1}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() for i, m in enumerate(r.json()["results"][:10], start=1): print(i, m["title"], m.get("release_date")) ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $chart = json_decode($body, true); foreach (array_slice($chart['results'], 0, 10) as $i => $m) { echo ($i + 1), ' ', $m['title'], ' ', $m['release_date'] ?? '', PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Chart struct { Results []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"results"` } func main() { url := "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var chart Chart if err := json.NewDecoder(res.Body).Decode(&chart); err != nil { panic(err) } for i, m := range chart.Results { if i == 10 { break } fmt.Println(i+1, m.Title, m.ReleaseDate) } } ``` ### Параметры | Параметр | Дзе | Абавязковы | Апісанне | | ------------- | ----- | ------------ | ------------------------------------------------------------------------------------------------------------ | | `media_type` | шлях | так | `all`, `movie`, `tv` або `person`. | | `time_window` | шлях | так | `day` або `week`. | | `api_key` | запыт | адзін з двух | Ваш ключ. Выкарыстоўвайце яго або загаловак `Authorization: Bearer`. | | `language` | запыт | не | Тэг TMDB, напрыклад `en-US` або `ru-RU`. Падтрымліваюцца 14 базавых моў, усё астатняе замяняецца англійскай. | | `page` | запыт | не | Нумар старонкі ад 1 да 500. Кожная старонка змяшчае 20 вынікаў. | ### Палі адказу | Поле | Тып | Заўвагі | | --------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | цэлы лік | Старонка, якую вы запыталі. | | `results` | масіў | Аб’екты фільмаў, серыялаў або персон, найлепшы ранг першым. | | `total_pages`, `total_results` | цэлы лік | Агульныя лікі для старонак. Чарты трэндаў паказваюць не болей за 500 старонак і 10000 вынікаў. | | `media_type` | радок | `movie`, `tv` або `person` у кожным запісе трэндаў. Чытайце яго, калі запытваеце `all`. | | `id` | цэлы лік | Выкарыстоўвайце яго са старонкамі [фільмы](https://amodb.dev/be/movies/), [серыялы](https://amodb.dev/be/tv-series/) або [персоны](https://amodb.dev/be/people/). | | `title`, `original_title` | радок | Запісы фільмаў. Запісы серыялаў выкарыстоўваюць `name` і `original_name`. | | `release_date`, `first_air_date` | радок | `YYYY-MM-DD` для запісаў фільмаў і серыялаў. | | `genre_ids` | масіў | Лікавыя id. Назвы бярыце са старонкі [жанры](https://amodb.dev/be/genres/). | | `popularity`, `vote_average`, `vote_count` | лік | Уваходныя даныя для рангу і зводная ацэнка карыстальнікаў. | | `poster_path`, `backdrop_path`, `profile_path` | радок або null | Дадайце да `https://img.amodb.dev/t/p/{size}`. | | `name`, `original_name`, `gender`, `known_for_department` | радок або цэлы лік | Запісы персон. `known_for` ёсць пустым масівам у запісах персон у трэндах. | ### Прыклад адказу ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/7ULXMNvmZSi13zN3EZjz8wbER9B.jpg", "genre_ids": [28, 53], "id": 1561726, "original_language": "en", "original_title": "Masterplan", "overview": "When a legendary thief sets his sights on the Mona Lisa, he recruits two young strangers to help him before...", "popularity": 189.8286, "poster_path": "/3x3AfF0qVwSUDDciTaNKcPHZUN8.jpg", "release_date": "2026-10-16", "title": "Masterplan", "video": false, "vote_average": 7.279, "vote_count": 61, "media_type": "movie" }, { "adult": false, "backdrop_path": "/mBZKC8ActTlM4W3HEGI1Cl1RtO3.jpg", "genre_ids": [878, 9648, 28], "id": 1058424, "original_language": "ko", "original_title": "호프", "overview": "In the remote South Korean village of Hope Harbor, police chief Bum-seok and officer Sung-ae are called to...", "popularity": 294.6518, "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg", "release_date": "2026-07-15", "title": "Hope", "video": false, "vote_average": 6.917, "vote_count": 246, "media_type": "movie" }, { "adult": false, "backdrop_path": "/5YfPIIMzGBkIjHt3PTXBWyfBTGS.jpg", "genre_ids": [28, 14], "id": 1153576, "original_language": "en", "original_title": "Street Fighter", "overview": "In 1993, estranged Street Fighters Ryu and Ken Masters are thrown back into combat when the mysterious Chun...", "popularity": 209.3923, "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg", "release_date": "2026-10-13", "title": "Street Fighter", "video": false, "vote_average": 6.316, "vote_count": 76, "media_type": "movie" } ], "total_pages": 500, "total_results": 10000 } ``` Адказ атрыманы з жывога API і скарочаны да 3 з 20 запісаў на старонцы 1. Доўгія радкі `overview` скарочаны, а рангі і лічбы мяняюцца пры кожным абнаўленні. ## Спісы фільмаў Чарты фільмаў маюць адну форму: масіў `results` з аб’ектамі фільмаў па старонках. `now_playing` і `upcoming` дадаюць аб’ект `dates` з `minimum` і `maximum`, акном выхаду, якое ахоплівае спіс. Усе чатыры прымаюць `language`, `page` і `region`. | Метад і шлях | Што вяртае | | ------------------------ | -------------------------------------------------------------------- | | `GET /movie/now_playing` | Фільмы, што выйшлі ў акне `dates` вакол сённяшняга дня, плюс `dates` | | `GET /movie/popular` | Фільмы, ранжыраваныя па бягучай папулярнасці | | `GET /movie/top_rated` | Фільмы, ранжыраваныя па ацэнцы карыстальнікаў | | `GET /movie/upcoming` | Фільмы з датай выхаду наперадзе, плюс `dates` | | `GET /movie/latest` | Адзін аб’ект фільма: найноўшы запіс у каталогу. Гэта не спіс | Сапраўдны аб’ект `dates` выглядае так: ```json { "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } } ``` `region` гэта код ISO 3166-1 вялікімі літарамі, напрыклад `DE` або `GB`. У `now_playing` і `upcoming` ён пакідае толькі назвы, што выйшлі ў гэтай краіне, таму спіс ёсць малой часткай сусветнага. Невядомы код вяртае пусты спіс. У `popular` і `top_rated` ён толькі замяняе `release_date` на мясцовую дату і не змяняе ранжыраванне. Каб убачыць, дзе ідзе фільм, спалучайце `now_playing` са старонкай [сеансы](https://amodb.dev/be/showtimes/). ## Спісы серыялаў Чарты серыялаў вяртаюць тыя ж палі старонак. Запісы выкарыстоўваюць `name`, `original_name`, `first_air_date` і `origin_country` замест назваў для фільмаў. Усе чатыры прымаюць `language` і `page`. | Метад і шлях | Што вяртае | Дадатковыя параметры | | ---------------------- | ------------------------------------------------------------- | -------------------- | | `GET /tv/airing_today` | Серыялы з эпізодам у эфіры сёння | `timezone` | | `GET /tv/on_the_air` | Серыялы з эпізодам у эфіры ў бліжэйшыя дні | `timezone` | | `GET /tv/popular` | Серыялы, ранжыраваныя па бягучай папулярнасці | няма | | `GET /tv/top_rated` | Серыялы, ранжыраваныя па ацэнцы карыстальнікаў | няма | | `GET /tv/latest` | Адзін аб’ект серыяла: найноўшы запіс у каталогу. Гэта не спіс | няма | `timezone` гэта назва IANA, напрыклад `Europe/Rome`. Яна вызначае, які каляндарны дзень лічыцца «сёння», таму `airing_today` вяртае розны набор для `Asia/Tokyo` і для `Pacific/Auckland`. У спісаў серыялаў няма параметра `region`. ## Спісы людзей `GET /person/popular` вяртае спіс людзей па старонках, ранжыраваных па папулярнасці, з `language` і `page`. Кожны запіс мае `id`, `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `popularity` і масіў `known_for` з не болей чым 3 картак фільмаў або серыялаў, кожная з `media_type`. Адкрыйце персону на старонцы [персоны](https://amodb.dev/be/people/). ```json { "page": 1, "results": [ { "adult": false, "gender": 1, "id": 1247604, "known_for_department": "Acting", "name": "Agnez Mo", "original_name": "Agnez Mo", "popularity": 45.8988, "profile_path": "/7GuBJxf5szQRCKLk3iG2ztfCo39.jpg", "known_for": [ { "adult": false, "backdrop_path": "/pF0qkRsrHkdYadPWY9AMeFZfcwk.jpg", "first_air_date": "2022-02-03", "genre_ids": [10759], "id": 108978, "name": "Reacher", "origin_country": ["US"], "original_language": "en", "original_name": "Reacher", "overview": "Jack Reacher, a veteran military police investigator, has just recently enter...", "popularity": 411.841, "poster_path": "/f1VCQIG2iCyOookdgOzwtUpwWC0.jpg", "vote_average": 8.1, "vote_count": 3508, "media_type": "tv" } ] } ], "total_pages": 1001, "total_results": 20001 } ``` amodb не прапануе `person/latest` і стужкі `changes`. ## Як абраць патрэбны спіс для экрана | Экран | Выклік | Абнаўленне | | ------------------------------ | ------------------------------------- | ----------------------------- | | Галоўны радок на старонцы | `/trending/all/week` | Не часцей чым раз у 30 хвілін | | Укладка «У кінатэатрах» | `/movie/now_playing` з вашым `region` | Не часцей чым раз у 30 хвілін | | Укладка «Хутка ў пракаце» | `/movie/upcoming` з вашым `region` | Не часцей чым раз у 30 хвілін | | Стужка «Сёння па ТБ» | `/tv/airing_today` з `timezone` | Не часцей чым раз у 30 хвілін | | Любімыя за ўвесь час | `/movie/top_rated` | Дастаткова раз у суткі | | Людзі, якіх шукаюць | `/trending/person/day` | Не часцей чым раз у 30 хвілін | | Самыя папулярныя людзі ў цэлым | `/person/popular` | Не часцей чым раз у 30 хвілін | ## Памылкі | HTTP | status_code | Калі | | ---- | ----------- | --------------------------------------------------------------------------------------------------------------- | | 401 | 7 | Ключ адсутнічае або няправільны. | | 402 | 36 | Тэрмін дзеяння плана скончыўся. | | 404 | 34 | Шляху не існуе, напрыклад з памылкай у назве спіса або `media_type` ці `time_window`, якіх няма ў спісах вышэй. | | 405 | 37 | Вы выкарысталі метад запісу на шляху спіса. | | 429 | 25 | Вы перавысілі ліміт запытаў у хвіліну. Пачакайце `Retry-After` секунд. | | 500 | 11 | `page` вышэй за 500. | Поўная табліца ёсць на старонцы [памылкі](https://amodb.dev/be/errors/). Ліміты па планах на старонцы [ліміты запытаў](https://amodb.dev/be/rate-limits/). ## Практычныя заўвагі - Edge кэшуе спісы трэндаў, папулярных, now playing і on the air на 30 хвілін, і кожны ключ дзеліць адзін запіс. Задачы абнаўлення, якая запускаецца раз у 30 хвілін, дастаткова. - Старонкі ідуць ад 1 да 500. У спісах папулярных `total_results` роўны 20001, гэта абмежаванне, а не рэальная колькасць. Далей за старонку 500 выкарыстоўвайце [пошук па фільтрах](https://amodb.dev/be/discover/) з `sort_by` і фільтрамі, які даходзіць да назваў, што чарт ніколі не паказвае. - Запісы спісаў змяшчаюць толькі палі, патрэбныя для карткі. Для працягласці, imdb_id або ўдзельнікаў выклічце [дэталі фільма](https://amodb.dev/be/movies/) з `append_to_response`, адзін раз для кожнай карткі, якую адкрывае карыстальнік. - `language` кіруе мовай назваў і апісанняў. Назвы без перакладу вяртаюцца ў арыгінальным тэксце, таму правярайце пустыя радкі, перш чым адлюстроўваць картку. - Захоўвайце `id` са спісу, а не месца. Рангі мяняюцца пры кожным абнаўленні. ## Пытанні і адказы ### Як доўга кэшуюцца спісы трэндаў і папулярных? Edge кэшуе спісы трэндаў, папулярных, now playing і on the air на 30 хвілін і падзяляе кожны запіс паміж ключамі. Апытванне часцей чым раз у 30 хвілін вяртае ту ж старонку і марна расходуе запыты. ### Колькі старонак можна чытаць са спісу? Старонкі ідуць ад 1 да 500 па 20 вынікаў, тыя ж межы, што ў TMDB. Для глыбейшага перагляду выкарыстоўвайце discover, які фільтруе па жанры, годзе, акцёрах або кампаніі замест таго, каб ісці за адным фіксаваным чартам. ### Якія спісы прымаюць параметр region? now_playing і upcoming прымаюць region як двухлітарны код краіны вялікімі літарамі, напрыклад GB, і пакідаюць толькі назвы, што выйшлі там. popular і top_rated прымаюць яго, але толькі замяняюць release_date на мясцовую дату. У спісах серыялаў region няма. airing_today і on_the_air выкарыстоўваюць timezone. ### Ці можна адфільтраваць чарт па жанры? На гэтых шляхах не. Запісы спісаў нясуць genre_ids для паказу. Каб фільтраваць па жанры, выкарыстоўвайце discover з with_genres, а id ператвараце ў назвы праз эндпоінты спісаў жанраў. ## Звязаныя старонкі - [API дэталяў фільма](https://amodb.dev/be/movies/): API дэталяў фільма з тымі ж шляхамі і JSON, што ў TMDB v3. Адзін фільм па id, а акцёры, рэйтынгі і настрой праз append_to_response, на 14 мовах. - [API серыялаў](https://amodb.dev/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду. - [Discover API](https://amodb.dev/be/discover/): Discover API з фільтрамі TMDB v3. Спіс фільмаў і серыялаў па жанры, акцёрах, кампаніі, ключавым слове, годзе, рэйтынгу і працягласці з сартаваннем. - [Жанры і даведачныя спісы](https://amodb.dev/be/genres/): API спіса жанраў з шляхамі TMDB v3: id жанраў фільмаў і серыялаў з перакладзенымі назвамі, а таксама спісы краін, моў, пасад, узроставых рэйтынгаў і сэрвісаў. - [Сеансы ў кінатэатрах](https://amodb.dev/be/showtimes/): API сеансаў фільмаў вяртае кінатэатры і час сеансаў фільма ў адной краіне або зводку па краінах. Далучайце яго да дэталяў або спалучайце з now_playing. - [Ліміты запытаў](https://amodb.dev/be/rate-limits/): amodb абмяжоўвае ключ па запытах у хвіліну ў слізгальным акне 60 секунд: 20, 40 або 120 па плане. Чытайце загалоўкі лімітаў і апрацоўвайце 429 праз Retry-After. Абноўлена: 2026-10-18. Source: https://amodb.dev/be/trending-lists/