# Ендпоінти трендів і списків > Ендпоінти трендів і списків повертають ранжовані сторінки фільмів, серіалів або персон. Використовуйте 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` | query | один із двох | Ваш ключ. Використовуйте його або заголовок `Authorization: Bearer`. | | `language` | query | ні | Тег TMDB, наприклад `en-US` або `ru-RU`. Обслуговується 14 базових мов, усе інше повертається до англійської. | | `page` | query | ні | Номер сторінки від 1 до 500. Кожна сторінка містить 20 результатів. | ### Поля відповіді | Поле | Тип | Примітки | | --------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | ціле число | Сторінка, яку ви запитали. | | `results` | масив | Об'єкти фільмів, серіалів або персон, найвищий ранг першим. | | `total_pages`, `total_results` | ціле число | Підсумки пагінації. Чарти трендів повідомляють щонайбільше 500 сторінок і 10000 результатів. | | `media_type` | рядок | `movie`, `tv` або `person` у кожному елементі трендів. Читайте його, коли запитуєте `all`. | | `id` | ціле число | Використовуйте його з розділами [фільми](https://amodb.dev/uk/movies/), [серіали](https://amodb.dev/uk/tv-series/) чи [персони](https://amodb.dev/uk/people/). | | `title`, `original_title` | рядок | Елементи фільмів. Елементи серіалів використовують `name` і `original_name`. | | `release_date`, `first_air_date` | рядок | `YYYY-MM-DD` для елементів фільмів і серіалів. | | `genre_ids` | масив | Числові id. Назви можна отримати в розділі [жанри](https://amodb.dev/uk/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/uk/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/uk/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/uk/errors/). Ліміти за тарифами наведено в розділі [ліміти запитів](https://amodb.dev/uk/rate-limits/). ## Практичні нотатки - Edge кешує списки trending, popular, now playing і on the air на 30 хвилин, і кожен ключ ділить той самий запис. Достатньо завдання оновлення, що запускається кожні 30 хвилин. - Сторінки йдуть від 1 до 500. Популярні списки повідомляють `total_results` 20001, це обмеження, а не реальна кількість. Далі сторінки 500 використовуйте [discover](https://amodb.dev/uk/discover/) із `sort_by` та фільтрами, які дістають назви, що чарт ніколи не показує. - Елементи списку містять лише поля, потрібні для картки. Щоб отримати тривалість, imdb_id чи акторський склад, викликайте [деталі фільму](https://amodb.dev/uk/movies/) з `append_to_response` один раз для кожної картки, яку відкрив користувач. - `language` керує мовою назв і описів. Назви без перекладу повертаються в оригінальному тексті, тож перед відображенням картки перевіряйте порожні рядки. - Зберігайте `id` зі списку, а не позицію. Ранги змінюються під час кожного оновлення. ## Запитання й відповіді ### Як довго кешуються списки трендів і популярних? Edge кешує списки trending, popular, 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/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами. - [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги. - [Discover API](https://amodb.dev/uk/discover/): Discover API з тими самими фільтрами, що й у TMDB v3. Фільми та серіали за жанром, акторами, компанією, роком, рейтингом, тривалістю й провайдером. - [Жанри та довідкові списки](https://amodb.dev/uk/genres/): API жанрів зі шляхами TMDB v3: id жанрів фільмів і серіалів з перекладеними назвами, списки країн, мов, посад, вікових рейтингів і стрімінгових провайдерів. - [Сеанси в кінотеатрах](https://amodb.dev/uk/showtimes/): API сеансів фільмів повертає кінотеатри та час показів фільму в одній країні або зведення по країнах. Додайте його до деталей або поєднайте з now_playing. - [Ліміти запитів](https://amodb.dev/uk/rate-limits/): amodb обмежує кожен ключ запитами на хвилину в ковзному вікні 60 секунд: 20, 40 або 120 за тарифом. Читайте заголовки ліміту й обробляйте 429 із Retry-After. Оновлено: 2026-10-18. Source: https://amodb.dev/uk/trending-lists/