# 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": 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 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": 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—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.468, "vote_count": 5684 } ], "total_pages": 39, "total_results": 772 } ``` ## Откриване на филми по филтри `GET /3/discover/movie` връща странициран списък с филми, които отговарят на всички подадени филтри, в избрания от вас ред. Това е ендпойнтът за страници за разглеждане, списъци „най-добри“ и препоръки по характеристики и не изисква текст `query`. Когато потребителят е въвел заглавие, ползвайте [търсене](https://amodb.dev/bg/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/bg/search/). | | `with_people` | заявка | не | Id на личности, които участват като актьорски състав или екип. | | `with_companies`, `without_companies` | заявка | не | Id на продуцентски компании, които да се включат или изключат. Запетаята и вертикалната черта работят както при `with_genres`. | | `with_keywords`, `without_keywords` | заявка | не | Id на ключови думи, които да се включат или изключат. Вижте [ключови думи](https://amodb.dev/bg/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/bg/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/bg/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/bg/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/bg/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/bg/errors/) и [лимити на заявките](https://amodb.dev/bg/rate-limits/). ## Практически бележки - Edge кешът държи всеки отделен набор от филтри 30 минути и го споделя между ключовете. Ключът на кеша се изгражда от сортираната заявка, така че редът на параметрите няма значение. - Страницата съдържа 20 записа, а последната е 500, така че един набор от филтри достига 10 000 записа. За да стигнете по-дълбоко, разбивайте заявката на времеви прозорци. Широк филтър отчита `total_results` със стойност 20001, което е таван, а не реален брой. - Винаги комбинирайте `sort_by=vote_average.desc` с `vote_count.gte`. Без него заглавия с малко гласове заемат върха. - Id във филтрите са числови. Id на личности вземайте през [търсене](https://amodb.dev/bg/search/), а id на жанрове и доставчици от [жанрове и справочни списъци](https://amodb.dev/bg/genres/). - За готови списъци като популярни или тези, които вървят в момента, вижте [тенденции и списъци](https://amodb.dev/bg/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/bg/search/): API за търсене със същите пътища и JSON като TMDB v3. Намира филми, сериали, личности, колекции, компании и ключови думи по текст, с филтър по година. - [Жанрове и справочни списъци](https://amodb.dev/bg/genres/): API за списък с жанрове с пътища на TMDB v3: id на жанрове за филми и сериали с преведени имена, списъци с държави, езици, длъжности, рейтинги и доставчици. - [Ендпойнти за тенденции и списъци](https://amodb.dev/bg/trending-lists/): API за филми в тенденция с пътища на TMDB v3: класации за ден и седмица, списъци в кината, популярни, най-добри и предстоящи, кеш 30 минути. - [API за ключови думи](https://amodb.dev/bg/keywords/): API за ключови думи с пътища на TMDB v3: тагове на сюжета, търсене на ключова дума, филмите ѝ и комбиниране на id с with_keywords в discover. - [Компании и мрежи](https://amodb.dev/bg/companies-networks/): Търсете продуцентски компании и мрежи с пътища на TMDB v3. Четете име, държава и лого по id, после филтрирайте discover по компания или мрежа. - [Лимити на заявките](https://amodb.dev/bg/rate-limits/): amodb ограничава всеки ключ по заявки в минута в плъзгащ се прозорец от 60 секунди: 20, 40 или 120. Заглавки за лимита и обработка на 429 с Retry-After. Обновено: 2026-10-18. Source: https://amodb.dev/bg/discover/