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