# Эндпоинты трендов и списков > Эндпоинты трендов и списков возвращают ранжированные страницы фильмов, сериалов или людей. Используйте 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/ru/movies/), [сериалы](https://amodb.dev/ru/tv-series/) или [люди](https://amodb.dev/ru/people/). | | `title`, `original_title` | строка | Элементы фильмов. У элементов сериалов `name` и `original_name`. | | `release_date`, `first_air_date` | строка | `YYYY-MM-DD` для элементов фильмов и сериалов. | | `genre_ids` | массив | Числовые id. Названия берутся из раздела [жанры](https://amodb.dev/ru/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/ru/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/ru/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/ru/errors/). Лимиты по тарифам на странице [лимиты запросов](https://amodb.dev/ru/rate-limits/). ## Практические заметки - CDN кэширует списки trending, popular, now playing и on the air на 30 минут, и все ключи используют одну и ту же запись. Достаточно задачи обновления раз в 30 минут. - Страницы идут от 1 до 500. Популярные списки сообщают `total_results` 20001: это предел, а не реальное число. За страницей 500 используйте [discover](https://amodb.dev/ru/discover/) с `sort_by` и фильтрами, он достает названия, которых чарт никогда не показывает. - Элементы списка содержат только поля, нужные для карточки. Для продолжительности, imdb_id или актеров вызовите [детали фильма](https://amodb.dev/ru/movies/) с `append_to_response` один раз для каждой карточки, которую открывает пользователь. - `language` задает язык названий и описаний. Названия без перевода приходят в оригинальном тексте, поэтому перед отрисовкой карточки проверяйте пустые строки. - Сохраняйте `id` из списка, а не позицию. Ранги меняются при каждом обновлении. ## Вопросы и ответы ### Как долго кэшируются списки трендов и популярных? CDN кэширует списки 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/ru/movies/): API деталей фильма с теми же путями и JSON, что в TMDB v3. Получите фильм по ID, добавьте актеров, рейтинги и настроения через append_to_response, на 14 языках. - [API сериалов](https://amodb.dev/ru/tv-series/): API сериалов с теми же путями и JSON, что в TMDB v3. Сериал по id с сезонами, телесетями и следующей серией, а также возрастные рейтинги и сервисы просмотра. - [Discover API](https://amodb.dev/ru/discover/): Discover API с фильтрами TMDB v3. Фильмы и сериалы по жанру, актеру, студии, ключевому слову, году, рейтингу, длительности и провайдеру, с сортировкой. - [Жанры и справочники](https://amodb.dev/ru/genres/): API списка жанров с путями TMDB v3: ID жанров фильмов и сериалов с названиями, а также списки стран, языков, должностей, рейтингов и провайдеров. - [Сеансы в кинотеатрах](https://amodb.dev/ru/showtimes/): API сеансов фильмов возвращает кинотеатры и время показов фильма в одной стране или сводку по странам. Добавляйте в детали фильма или сочетайте с now_playing. - [Лимиты запросов](https://amodb.dev/ru/rate-limits/): amodb ограничивает ключ запросами в минуту в скользящем окне 60 секунд: 20, 40 или 120 по тарифу. Читайте заголовки лимита и обрабатывайте 429 с Retry-After. Обновлено: 2026-10-18. Source: https://amodb.dev/ru/trending-lists/