# Discover API > Discover выдае фільмы праз GET /3/discover/movie і серыялы праз GET /3/discover/tv, адфільтраваныя і адсартаваныя па абраных параметрах: жанр, акцёры, здымачная група, кампанія, ключавое слова, даты, рэйтынг, галасы, працягласць, мова і стрымінгавы сэрвіс. JSON адпавядае TMDB v3, а вынікі кэшуюцца на 30 хвілін. ## Эндпоінт `GET /3/discover/movie` ```bash curl "https://api.amodb.dev/3/discover/movie?with_genres=878&sort_by=vote_average.desc&vote_count.gte=1000" \ -H "Authorization: Bearer $AMODB_KEY" ``` Адказ: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/wLWvHcQz7N13DvSOTV7bHgwGXpT.jpg", "genre_ids": [ 878, 12 ], "id": 687163, "original_language": "en", "original_title": "Project Hail Mary", "overview": "Science teacher Ryland Grace wakes up on a spaceship light years from home with no recollection of who he is or how he got there. As his memory returns, he begins to uncover his mission: solve the riddle of the mysterious substance causing...", "popularity": 101.0341, "poster_path": "/yihdXomYb5kTeSivtFndMy5iDmf.jpg", "release_date": "2026-03-15", "title": "Project Hail Mary", "video": false, "vote_average": 8.635, "vote_count": 8355 }, { "adult": false, "backdrop_path": "/Ys8UIGWJpd2TMuQk8fU77W3mBz.jpg", "genre_ids": [ 12, 18, 878 ], "id": 157336, "original_language": "en", "original_title": "Interstellar", "overview": "The adventures of a group of explorers who make use of a newly discovered wormhole to surpass the limitations on human space travel and conquer the vast distances involved in an interstellar voyage.", "popularity": 74.3949, "poster_path": "/yQvGrMoipbRoddT0ZR8tPoR7NfX.jpg", "release_date": "2014-11-04", "title": "Interstellar", "video": false, "vote_average": 8.491, "vote_count": 41529 }, { "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": 663.5004, "poster_path": "/bjiS5ipwxb9JFy3XRRN4OAilSeX.jpg", "release_date": "2026-07-29", "title": "Spider-Man: Brand New Day", "video": false, "vote_average": 8.466, "vote_count": 5714 } ], "total_pages": 39, "total_results": 772 } ``` ## Пошук фільмаў па фільтрах `GET /3/discover/movie` вяртае пастаронкавы спіс фільмаў, якія адпавядаюць усім адпраўленым фільтрам, у абраным парадку. Гэта эндпоінт для старонак агляду, спісаў «лепшае» і рэкамендацый па фасетах, і тэкст `query` яму не патрэбны. Калі карыстальнік увёў назву, выкарыстоўвайце [пошук](https://amodb.dev/be/search/). У прыкладзе паказаны фантастычныя фільмы (id жанру `878`) не менш чым з 1000 галасоў, спачатку з лепшым рэйтынгам. ```bash curl -sSf --get "https://api.amodb.dev/3/discover/movie" \ --data-urlencode "with_genres=878" \ --data-urlencode "sort_by=vote_average.desc" \ --data-urlencode "vote_count.gte=1000" \ --data-urlencode "language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ with_genres: '878', sort_by: 'vote_average.desc', 'vote_count.gte': '1000', language: 'en-US', }); const res = await fetch(`https://api.amodb.dev/3/discover/movie?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { results, total_pages } = await res.json(); console.log(`page 1 of ${total_pages}`); for (const m of results.slice(0, 5)) console.log(m.vote_average, m.title, m.release_date); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/discover/movie", params={ "with_genres": 878, "sort_by": "vote_average.desc", "vote_count.gte": 1000, "language": "en-US", }, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() data = r.json() print("page 1 of", data["total_pages"]) for m in data["results"][:5]: print(m["vote_average"], m["title"], m["release_date"]) ``` ```php 878, 'sort_by' => 'vote_average.desc', 'vote_count.gte' => 1000, 'language' => 'en-US', ]); $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => 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"); } $data = json_decode($body, true); foreach (array_slice($data['results'], 0, 5) as $m) { echo $m['vote_average'], ' ', $m['title'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type Page struct { TotalPages int `json:"total_pages"` Results []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` VoteAverage float64 `json:"vote_average"` } `json:"results"` } func main() { q := url.Values{ "with_genres": {"878"}, "sort_by": {"vote_average.desc"}, "vote_count.gte": {"1000"}, "language": {"en-US"}, } req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/discover/movie?"+q.Encode(), 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 p Page if err := json.NewDecoder(res.Body).Decode(&p); err != nil { panic(err) } fmt.Println("pages:", p.TotalPages) for _, m := range p.Results { fmt.Println(m.VoteAverage, m.Title, m.ReleaseDate) } } ``` ### Параметры | Параметр | Дзе | Абавязковы | Апісанне | | ------------------------------------------------------ | ----- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_key` | запыт | адзін з двух | Ваш ключ. Выкарыстоўвайце яго або загаловак `Authorization: Bearer`. | | `sort_by` | запыт | не | Поле і напрамак, напрыклад `vote_average.desc`. Палі: `popularity`, `vote_average`, `vote_count`, `primary_release_date`, `revenue`, `title`, `original_title`, кожнае з `.asc` або `.desc`. `title` і `original_title` абодва сартуюць па арыгінальнай назве. Невядомае значэнне замяняецца на `popularity.desc`, якое таксама дзейнічае па змаўчанні. | | `with_genres` | запыт | не | Id жанраў. Коска азначае І, вертыкальная рыска азначае АБО. | | `without_genres` | запыт | не | Id жанраў, якія трэба выключыць. | | `with_cast`, `with_crew` | запыт | не | Id персон. Знайдзіце іх праз [пошук](https://amodb.dev/be/search/). | | `with_people` | запыт | не | Id персон, якія ёсць у акцёрскім складзе або ў здымачнай групе. | | `with_companies`, `without_companies` | запыт | не | Id вытворчых кампаній, якіх трэба ўключыць або выключыць. Коска і вертыкальная рыска працуюць так жа, як у `with_genres`. | | `with_keywords`, `without_keywords` | запыт | не | Id ключавых слоў, якія трэба ўключыць або выключыць. Гл. [ключавыя словы](https://amodb.dev/be/keywords/). | | `with_origin_country` | запыт | не | Двухлітарны код краіны вытворчасці вялікімі літарамі, напрыклад `FR`. | | `primary_release_year` | запыт | не | Чатырохзначны год асноўнай даты выхаду. | | `year` | запыт | не | Чатырохзначны год. Супадае з любой датай выхаду ў гэтым годзе, таму вяртае больш фільмаў, чым `primary_release_year`. | | `primary_release_date.gte`, `primary_release_date.lte` | запыт | не | Ніжняя і верхняя мяжа асноўнай даты выхаду, `YYYY-MM-DD`. | | `release_date.gte`, `release_date.lte` | запыт | не | Ніжняя і верхняя мяжа любой даты выхаду ў любой краіне, `YYYY-MM-DD`. | | `region` | запыт | не | Двухлітарны код краіны вялікімі літарамі. Замяняе `release_date` у кожным выніку датай у гэтай краіне. Фільмы не выдаляе. | | `certification_country`, `certification` | запыт | не | Фільтр узроставага рэйтынгу, напрыклад `US` і `PG`. Без краіны `certification` ігнаруецца. `certification.gte` і `certification.lte` задаюць дыяпазон. | | `vote_average.gte`, `vote_average.lte` | запыт | не | Мінімальная і максімальная сярэдняя ацэнка, ад 0 да 10. | | `vote_count.gte`, `vote_count.lte` | запыт | не | Мінімальная і максімальная колькасць галасоў. | | `with_runtime.gte`, `with_runtime.lte` | запыт | не | Мінімальная і максімальная працягласць у хвілінах. | | `with_original_language` | запыт | не | Арыгінальная мова ў выглядзе двухлітарнага кода, напрыклад `fr` або `ko`. | | `with_watch_providers` | запыт | не | Id стрымінгавых сэрвісаў. Патрабуе `watch_region`, без яго ігнаруецца. Id бяруцца са старонкі [жанры і даведачныя спісы](https://amodb.dev/be/genres/). | | `watch_region` | запыт | не | Двухлітарны код краіны вялікімі літарамі для даступнасці сэрвісу. | | `include_adult` | запыт | не | Прымаецца і ігнаруецца. Фільмы для дарослых ніколі не вяртаюцца. | | `language` | запыт | не | Тэг TMDB, напрыклад `en-US` або `pl-PL`. Падтрымліваюцца 14 базавых моў. Па змаўчанні `en-US`. | | `page` | запыт | не | Нумар старонкі ад 1 да 500. Па змаўчанні 1. | ### Палі адказу | Поле | Тып | Заўвагі | | ------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page`, `total_pages`, `total_results` | цэлы лік | Пастаронкавая разбіўка для гэтага набору фільтраў. Шырокія фільтры паказваюць не болей за 1001 старонку і 20001 вынік, але чытаць можна толькі старонкі з 1 па 500. | | `results` | масіў | Да 20 фільмаў. Пусты, калі няма фільма, які адпавядае ўсім фільтрам. | | `id` | цэлы лік | Id фільма для [дэталяў фільма](https://amodb.dev/be/movies/). | | `title`, `original_title`, `overview` | радок | Лакалізаваны тэкст і арыгінальная назва. | | `original_language` | радок | Двухлітарны код мовы, на якой зняты фільм. | | `release_date` | радок | `YYYY-MM-DD`. | | `genre_ids` | масіў цэлых лікаў | Толькі id. Супастаўце іх з назвамі праз `/genre/movie/list`. | | `poster_path`, `backdrop_path` | радок або null | Дадайце да `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count`, `popularity` | лік | Значэнні ацэнкі і рэйтынгу. | | `adult`, `video` | лагічнае значэнне | `adult` заўсёды `false`. | ### Прыклад адказу ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/wLWvHcQz7N13DvSOTV7bHgwGXpT.jpg", "genre_ids": [878, 12], "id": 687163, "original_language": "en", "original_title": "Project Hail Mary", "overview": "Science teacher Ryland Grace wakes up on a spaceship light years from home with no recollection of who he i...", "popularity": 101.0341, "poster_path": "/yihdXomYb5kTeSivtFndMy5iDmf.jpg", "release_date": "2026-03-15", "title": "Project Hail Mary", "video": false, "vote_average": 8.635, "vote_count": 8354 }, { "adult": false, "backdrop_path": "/Ys8UIGWJpd2TMuQk8fU77W3mBz.jpg", "genre_ids": [12, 18, 878], "id": 157336, "original_language": "en", "original_title": "Interstellar", "overview": "The adventures of a group of explorers who make use of a newly discovered wormhole to surpass the limitatio...", "popularity": 74.3949, "poster_path": "/yQvGrMoipbRoddT0ZR8tPoR7NfX.jpg", "release_date": "2014-11-04", "title": "Interstellar", "video": false, "vote_average": 8.491, "vote_count": 41526 }, { "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...", "popularity": 663.5004, "poster_path": "/bjiS5ipwxb9JFy3XRRN4OAilSeX.jpg", "release_date": "2026-07-29", "title": "Spider-Man: Brand New Day", "video": false, "vote_average": 8.468, "vote_count": 5684 } ], "total_pages": 39, "total_results": 772 } ``` Адказ атрыманы з жывога API для прыкладу запыту. Паказана 3 з 20 запісаў на старонцы 1, доўгія радкі `overview` скарочаны. ## Спалучэнне фільтраў Асобныя параметры спалучаюцца праз І. Унутры аднаго параметра коска азначае І, а вертыкальная рыска азначае АБО. У сырым URL вертыкальная рыска запісваецца як `%7C`, а кліенты, што кадуюць значэнні запыту, робяць гэта за вас. | Мэта | Запыт | | ------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Лепшая фантастыка з дастатковай колькасцю галасоў | `/discover/movie?with_genres=878&sort_by=vote_average.desc&vote_count.gte=1000` | | Баявік або прыгоды | `/discover/movie?with_genres=28%7C12` | | Баявік, але не анімацыя | `/discover/movie?with_genres=28&without_genres=16` | | Адзін акцёр з адным рэжысёрам | `/discover/movie?with_cast=6193&with_crew=525` | | Доўгія фільмы за адзін год | `/discover/movie?primary_release_year=2010&with_runtime.gte=150` | | Выхады ў межах дат | `/discover/movie?primary_release_date.gte=2026-10-01&primary_release_date.lte=2026-10-31` | | Фільмы на адной арыгінальнай мове | `/discover/movie?with_original_language=fr` | | Стрымінг у адной краіне | `/discover/movie?with_watch_providers=8&watch_region=US` | | Фільмы з рэйтынгам R у ЗША | `/discover/movie?certification_country=US&certification=R` | | Без ключавога слова | `/discover/movie?with_keywords=818&without_keywords=4565` | `with_original_language` фільтруе па мове, на якой зняты фільм, і прымае коды па-за 14 падтрымліванымі мовамі, напрыклад `ja` або `ko`. Мову тэксту ў адказе па-ранейшаму вызначае параметр `language`. У радку са стрымінгавым сэрвісам `8` гэта Netflix. Id сэрвісаў чытайце з `/watch/providers/movie`. ## Пошук серыялаў па фільтрах `GET /3/discover/tv` выкарыстоўвае тую ж структуру адказу і тую ж пастаронкавую разбіўку. Запісы ўтрымліваюць `name`, `original_name`, `first_air_date`, `origin_country` і `genre_ids`, а id жанраў бяруцца з `/genre/tv/list`, дзе сабраны аб’яднаныя id для серыялаў, напрыклад `10765` для Sci-Fi і Fantasy. | Параметр | Апісанне | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `first_air_date.gte`, `first_air_date.lte` | Ніжняя і верхняя мяжа даты першага эфіру, `YYYY-MM-DD`. | | `first_air_date_year` | Чатырохзначны год даты першага эфіру. | | `air_date.gte`, `air_date.lte` | Ніжняя і верхняя мяжа дат, калі ў серыяла выходзяць эпізоды, `YYYY-MM-DD`. | | `with_networks` | Id тэлеканалаў. Знайдзіце іх на старонцы [кампаніі і тэлеканалы](https://amodb.dev/be/companies-networks/). | | `with_status` | Лікавы код статусу: `0` серыял працягваецца, `2` у вытворчасці, `3` завершаны, `4` закрыты. | | `with_type` | Лікавы тып шоу: `0` дакументальнае, `1` навіны, `2` мініседыял, `3` рэаліці, `4` сцэнарнае, `5` ток-шоу, `6` відэа. | | `sort_by` | `popularity`, `vote_average`, `vote_count`, `first_air_date`, `name` або `original_name`, кожнае з `.asc` або `.desc`. `name` і `original_name` абодва сартуюць па арыгінальнай назве. | | `with_genres`, `without_genres`, `with_companies`, `with_keywords`, `without_keywords` | Тыя ж правілы, што і для фільмаў. | | `vote_average.gte`, `vote_count.gte`, `with_runtime.gte`, `with_runtime.lte`, `with_original_language` | Тыя ж правілы, што і для фільмаў. | | `with_watch_providers`, `watch_region`, `language`, `page` | Тыя ж правілы, што і для фільмаў. | Запыт `/discover/tv?first_air_date.gte=2025-01-01&with_genres=18&vote_count.gte=100&sort_by=popularity.desc` вяртае драматычныя серыялы, што пачалі выходзіць у 2025 годзе або пазней. Падрабязнасці па выніку глядзіце на старонцы [серыялы](https://amodb.dev/be/tv-series/). ## Памылкі | HTTP | status_code | Калі | | ---- | ----------- | ------------------------------------------------------------------- | | 401 | 7 | Ключ адсутнічае або няправільны. | | 402 | 36 | Тэрмін дзеяння плана скончыўся. | | 405 | 37 | Вы выклікалі метад запісу. | | 429 | 25 | Перавышаны ліміт запытаў у хвіліну. Пачакайце `Retry-After` секунд. | | 500 | 11 | Значэнне `page` па-за дыяпазонам ад 1 да 500. | | 504 | 24 | Бэкенд не адказаў своечасова. Паўтарыце запыт адзін раз. | Набор фільтраў, пад які нічога не падыходзіць, не з’яўляецца памылкай. Вы атрымаеце HTTP 200 з пустым масівам `results` і `total_results`, роўным 0. Гл. [памылкі](https://amodb.dev/be/errors/) і [ліміты запытаў](https://amodb.dev/be/rate-limits/). ## Практычныя заўвагі - Edge-кэш захоўвае кожны асобны набор фільтраў 30 хвілін і падзяляе яго паміж ключамі. Ключ кэшу будуецца па адсартаваным запыце, таму парадак вашых параметраў не мае значэння. - На старонцы 20 запісаў, апошняя старонка 500, таму адзін набор фільтраў дае да 10 000 запісаў. Каб пайсці глыбей, дзяліце запыт на вокны дат. Шырокі фільтр паказвае `total_results`, роўны 20001, гэта абмежаванне, а не рэальная колькасць. - Заўсёды спалучайце `sort_by=vote_average.desc` з `vote_count.gte`. Без гэтага ўверсе збіраюцца фільмы з некалькімі галасамі. - Id у фільтрах лікавыя. Id персон бярыце праз [пошук](https://amodb.dev/be/search/), а id жанраў і стрымінгавых сэрвісаў са старонкі [жанры і даведачныя спісы](https://amodb.dev/be/genres/). - Гатовыя спісы, напрыклад папулярныя або тыя, што зараз у пракаце, глядзіце на старонцы [трэнды і спісы](https://amodb.dev/be/trending-lists/). ## Пытанні і адказы ### Як глыбока можна гартаць вынікі discover? Параметр page прымае значэнні ад 1 да 500, на старонцы 20 запісаў, таму адзін набор фільтраў дае максімум 10 000 запісаў. Каб прачытаць больш, падзяліце запыт на вокны дат праз primary_release_date.gte і .lte. ### Як спалучаць жанры праз І і АБО? Унутры аднаго параметра коска азначае І, а вертыкальная рыска азначае АБО. У сырым URL рыска запісваецца як %7C. Асобныя параметры заўсёды спалучаюцца праз І. ### Чаму сартаванне па рэйтынгу вяртае невядомыя фільмы? Першым у спісе аказваецца фільм з некалькімі ідэальнымі галасамі. Дадайце vote_count.gte, напрыклад 1000, каб па vote_average ранжыраваліся толькі фільмы з дастатковай колькасцю галасоў. ### Наколькі свежыя вынікі discover? Edge-кэш захоўвае кожны асобны набор фільтраў 30 хвілін і падзяляе яго паміж ключамі. Кожны выклік усё роўна ўлічваецца ў вашым ліміце запытаў у хвіліну, бо праверка ліміту адбываецца да кэшу. ## Звязаныя старонкі - [API пошуку](https://amodb.dev/be/search/): API пошуку з шляхамі і JSON як у TMDB v3. Фільмы, серыялы, персоны, калекцыі, кампаніі і ключавыя словы па тэксце, з фільтрамі па годзе і старонкамі. - [Жанры і даведачныя спісы](https://amodb.dev/be/genres/): API спіса жанраў з шляхамі TMDB v3: id жанраў фільмаў і серыялаў з перакладзенымі назвамі, а таксама спісы краін, моў, пасад, узроставых рэйтынгаў і сэрвісаў. - [Эндпоінты трэндаў і спісаў](https://amodb.dev/be/trending-lists/): API трэндавых фільмаў з шляхамі TMDB v3: чарты за дзень і тыдзень, спісы зараз у пракаце, папулярных, лепшых і хутка ў пракаце, кэш 30 хвілін. - [API ключавых слоў](https://amodb.dev/be/keywords/): API ключавых слоў з шляхамі TMDB v3: тэгі сюжэта фільма або серыяла, пошук ключавога слова, яго фільмы і спалучэнне id з with_keywords у discover. - [Кампаніі і тэлеканалы](https://amodb.dev/be/companies-networks/): Шукайце кінакампаніі і тэлеканалы па шляхах TMDB v3. Чытайце назву, краіну і лагатып па id, потым фільтруйце discover па id кампаніі або тэлеканала. - [Ліміты запытаў](https://amodb.dev/be/rate-limits/): amodb абмяжоўвае ключ па запытах у хвіліну ў слізгальным акне 60 секунд: 20, 40 або 120 па плане. Чытайце загалоўкі лімітаў і апрацоўвайце 429 праз Retry-After. Абноўлена: 2026-10-18. Source: https://amodb.dev/be/discover/