# Discover API > Discover vypisuje filmy na GET /3/discover/movie a seriály na GET /3/discover/tv, filtrované a řazené podle zvolených parametrů: žánr, obsazení, štáb, společnost, klíčové slovo, data, hodnocení, hlasy, délka, jazyk a poskytovatel streamování. JSON odpovídá TMDB v3 a výsledky se cachují 30 minut. ## Endpoint `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" ``` Odpověď: ```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 } ``` ## Discover pro filmy `GET /3/discover/movie` vrací stránkovaný seznam filmů, které odpovídají všem odeslaným filtrům, v pořadí podle vašeho výběru. Je to endpoint pro stránky s procházením, seznamy „nejlepších“ a doporučení podle fasety a nepotřebuje text `query`. Když máte titul zadaný uživatelem, použijte místo něj [vyhledávání](https://amodb.dev/cs/search/). Příklad vypíše sci-fi filmy (ID žánru `878`) s alespoň 1000 hlasy, nejlépe hodnocené první. ```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) } } ``` ### Parametry | Parametr | Kde | Povinný | Popis | | ------------------------------------------------------ | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_key` | query | jeden ze dvou | Váš klíč. Použijte jej, nebo hlavičku `Authorization: Bearer`. | | `sort_by` | query | ne | Pole a směr, například `vote_average.desc`. Pole: `popularity`, `vote_average`, `vote_count`, `primary_release_date`, `revenue`, `title`, `original_title`, každé s `.asc` nebo `.desc`. `title` i `original_title` řadí podle původního názvu. Neznámá hodnota se vrátí k `popularity.desc`, což je i výchozí. | | `with_genres` | query | ne | ID žánrů. Čárka znamená AND, znak svislé čáry OR. | | `without_genres` | query | ne | ID žánrů k vyloučení. | | `with_cast`, `with_crew` | query | ne | ID osob. Najdete je přes [vyhledávání](https://amodb.dev/cs/search/). | | `with_people` | query | ne | ID osob, které se objevují jako obsazení nebo štáb. | | `with_companies`, `without_companies` | query | ne | ID produkčních společností k vyžadování nebo vyloučení. Čárka a svislá čára fungují jako u `with_genres`. | | `with_keywords`, `without_keywords` | query | ne | ID klíčových slov k vyžadování nebo vyloučení. Viz [klíčová slova](https://amodb.dev/cs/keywords/). | | `with_origin_country` | query | ne | Dvoupísmenný kód produkční země velkými písmeny, například `FR`. | | `primary_release_year` | query | ne | Čtyřmístný rok primárního data vydání. | | `year` | query | ne | Čtyřmístný rok. Odpovídá libovolnému datu vydání v tom roce, takže vrací víc titulů než `primary_release_year`. | | `primary_release_date.gte`, `primary_release_date.lte` | query | ne | Dolní a horní mez primárního data vydání, `YYYY-MM-DD`. | | `release_date.gte`, `release_date.lte` | query | ne | Dolní a horní mez libovolného data vydání v jakékoli zemi, `YYYY-MM-DD`. | | `region` | query | ne | Dvoupísmenný kód země velkými písmeny. Nahradí `release_date` v každém výsledku datem v dané zemi. Tituly neodstraňuje. | | `certification_country`, `certification` | query | ne | Filtr věkového hodnocení, například `US` a `PG`. `certification` se bez země ignoruje. `certification.gte` a `certification.lte` udávají rozsah. | | `vote_average.gte`, `vote_average.lte` | query | ne | Minimální a maximální průměrné skóre, 0 až 10. | | `vote_count.gte`, `vote_count.lte` | query | ne | Minimální a maximální počet hlasů. | | `with_runtime.gte`, `with_runtime.lte` | query | ne | Minimální a maximální délka v minutách. | | `with_original_language` | query | ne | Původní jazyk jako dvoupísmenný kód, například `fr` nebo `ko`. | | `with_watch_providers` | query | ne | ID poskytovatelů. Vyžaduje `watch_region` a bez něj se ignoruje. ID pocházejí ze stránky [žánry a číselníky](https://amodb.dev/cs/genres/). | | `watch_region` | query | ne | Dvoupísmenný kód země velkými písmeny pro dostupnost poskytovatele. | | `include_adult` | query | ne | Přijímá se a ignoruje. Tituly pro dospělé se nikdy nevracejí. | | `language` | query | ne | Tag TMDB, například `en-US` nebo `pl-PL`. Podporuje se 14 základních jazyků. Výchozí `en-US`. | | `page` | query | ne | Číslo stránky od 1 do 500. Výchozí 1. | ### Pole odpovědi | Pole | Typ | Poznámky | | ------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `page`, `total_pages`, `total_results` | integer | Stránkování pro tuto sadu filtrů. Široké filtry hlásí nejvýše 1001 stránek a 20001 výsledků, ale číst lze jen stránky 1 až 500. | | `results` | array | Až 20 filmů. Prázdné, když žádný titul nesplňuje všechny filtry. | | `id` | integer | ID filmu pro [detail filmu](https://amodb.dev/cs/movies/). | | `title`, `original_title`, `overview` | string | Lokalizovaný text a původní název. | | `original_language` | string | Dvoupísmenný kód jazyka, ve kterém byl film natočen. | | `release_date` | string | `YYYY-MM-DD`. | | `genre_ids` | array of integers | Jen ID. Na názvy je převeďte přes `/genre/movie/list`. | | `poster_path`, `backdrop_path` | string nebo null | Připojte k `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count`, `popularity` | number | Skóre a hodnoty pořadí. | | `adult`, `video` | boolean | `adult` je vždy `false`. | ### Příklad odpovědi ```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 } ``` Odpověď byla stažena z živého API pro příkladový požadavek. Je zkrácena na 3 z 20 položek na stránce 1 a dlouhé řetězce `overview` jsou zkráceny. ## Kombinování filtrů Samostatné parametry se kombinují přes AND. Uvnitř jednoho parametru znamená čárka AND a znak svislé čáry OR. V surové URL se svislá čára píše `%7C` a klienti, kteří kódují hodnoty dotazu, to udělají za vás. | Cíl | Požadavek | | ------------------------------------------ | ----------------------------------------------------------------------------------------- | | Nejlépe hodnocené sci-fi s dostatkem hlasů | `/discover/movie?with_genres=878&sort_by=vote_average.desc&vote_count.gte=1000` | | Akční nebo dobrodružné | `/discover/movie?with_genres=28%7C12` | | Akční, ale ne animované | `/discover/movie?with_genres=28&without_genres=16` | | Jeden herec s jedním režisérem | `/discover/movie?with_cast=6193&with_crew=525` | | Dlouhé filmy z jednoho roku | `/discover/movie?primary_release_year=2010&with_runtime.gte=150` | | Premiéry v okně dat | `/discover/movie?primary_release_date.gte=2026-10-01&primary_release_date.lte=2026-10-31` | | Filmy v jednom původním jazyce | `/discover/movie?with_original_language=fr` | | Streaming v jedné zemi | `/discover/movie?with_watch_providers=8&watch_region=US` | | S hodnocením R v USA | `/discover/movie?certification_country=US&certification=R` | | Bez klíčového slova | `/discover/movie?with_keywords=818&without_keywords=4565` | `with_original_language` filtruje podle jazyka, ve kterém byl titul natočen, a přijímá i kódy mimo 14 podporovaných jazyků, například `ja` nebo `ko`. Jazyk vráceného textu stále určuje parametr `language`. V řádku s poskytovatelem je `8` Netflix. ID poskytovatelů čtěte z `/watch/providers/movie`. ## Discover pro seriály `GET /3/discover/tv` používá stejný obal a stránkování. Položky obsahují `name`, `original_name`, `first_air_date`, `origin_country` a `genre_ids` a ID žánrů pocházejí z `/genre/tv/list`, který obsahuje sloučená seriálová ID, například `10765` pro Sci-Fi a fantasy. | Parametr | Popis | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `first_air_date.gte`, `first_air_date.lte` | Dolní a horní mez data prvního vysílání, `YYYY-MM-DD`. | | `first_air_date_year` | Čtyřmístný rok data prvního vysílání. | | `air_date.gte`, `air_date.lte` | Dolní a horní mez dat, kdy seriál vysílá epizody, `YYYY-MM-DD`. | | `with_networks` | ID sítí. Najdete je na stránce [společnosti a televizní sítě](https://amodb.dev/cs/companies-networks/). | | `with_status` | Číselný kód stavu: `0` pokračující seriál, `2` ve výrobě, `3` skončil, `4` zrušen. | | `with_type` | Číselný typ pořadu: `0` dokument, `1` zprávy, `2` minisérie, `3` reality, `4` scénářový, `5` talk show, `6` video. | | `sort_by` | `popularity`, `vote_average`, `vote_count`, `first_air_date`, `name` nebo `original_name`, každé s `.asc` nebo `.desc`. `name` i `original_name` řadí podle původního názvu. | | `with_genres`, `without_genres`, `with_companies`, `with_keywords`, `without_keywords` | Stejná pravidla jako u filmů. | | `vote_average.gte`, `vote_count.gte`, `with_runtime.gte`, `with_runtime.lte`, `with_original_language` | Stejná pravidla jako u filmů. | | `with_watch_providers`, `watch_region`, `language`, `page` | Stejná pravidla jako u filmů. | Požadavek jako `/discover/tv?first_air_date.gte=2025-01-01&with_genres=18&vote_count.gte=100&sort_by=popularity.desc` vypíše dramatické seriály, které začaly v roce 2025 nebo později. Výsledek podrobně čtěte na stránce [seriály](https://amodb.dev/cs/tv-series/). ## Chyby | HTTP | status_code | Kdy | | ---- | ----------- | ------------------------------------------------------------------------------------- | | 401 | 7 | Klíč chybí nebo je nesprávný. | | 402 | 36 | Platnost tarifu skončila. | | 405 | 37 | Zavolali jste metodu pro zápis. | | 429 | 25 | Překročen počet požadavků za minutu. Počkejte tolik sekund, kolik říká `Retry-After`. | | 500 | 11 | Hodnota `page` mimo 1 až 500. | | 504 | 24 | Backend neodpověděl včas. Zkuste to jednou znovu. | Sada filtrů, která nic nenajde, není chyba. Dostanete HTTP 200 s prázdným polem `results` a `total_results` rovným 0. Viz [chyby](https://amodb.dev/cs/errors/) a [limity požadavků](https://amodb.dev/cs/rate-limits/). ## Praktické poznámky - Edge cachuje každou odlišnou sadu filtrů 30 minut a sdílí ji mezi klíči. Klíč cache používá seřazený dotaz, takže na pořadí parametrů nezáleží. - Stránka obsahuje 20 položek a poslední stránka je 500, takže jedna sada filtrů dosáhne 10 000 položek. Pro hlubší průchod dělte podle oken dat. Široký filtr hlásí `total_results` 20001, což je strop, ne skutečný počet. - `sort_by=vote_average.desc` vždy spárujte s `vote_count.gte`. Bez něj nahoře zaplní tituly s pár hlasy. - ID ve filtrech jsou číselná. ID osob získáte přes [vyhledávání](https://amodb.dev/cs/search/) a ID žánrů a poskytovatelů ze stránky [žánry a číselníky](https://amodb.dev/cs/genres/). - Hotové seznamy, například populární nebo aktuálně v kinech, najdete na stránce [trendy a seznamy](https://amodb.dev/cs/trending-lists/). ## Otázky a odpovědi ### Jak hluboko mohu stránkovat výsledky discover? Parametr page jde od 1 do 500 s 20 položkami na stránku, takže jedna sada filtrů dosáhne nejvýše 10 000 položek. Chcete-li číst víc, rozdělte dotaz na okna dat pomocí primary_release_date.gte a .lte. ### Jak kombinovat žánry přes AND a OR? Uvnitř jednoho parametru znamená čárka AND a znak svislé čáry OR. Svislá čára se v surové URL píše %7C. Samostatné parametry se vždy kombinují přes AND. ### Proč řazení podle hodnocení vrací neznámé tituly? Titul s hrstkou dokonalých hlasů skončí na vrcholu. Přidejte vote_count.gte, například 1000, aby se podle vote_average řadily jen tituly s dostatkem hlasů. ### Jak čerstvé jsou výsledky discover? Edge cachuje každou odlišnou sadu filtrů 30 minut a sdílí ji mezi klíči. Každé volání se přesto počítá do vašich požadavků za minutu, protože limit se vyhodnocuje před cache. ## Související stránky - [API vyhledávání](https://amodb.dev/cs/search/): API vyhledávání se stejnými cestami a JSON jako TMDB v3. Najděte filmy, seriály, osoby, kolekce, společnosti a klíčová slova podle textu s filtrem roku. - [Žánry a číselníky](https://amodb.dev/cs/genres/): Seznam žánrů API s cestami TMDB v3: ID žánrů filmů a seriálů s přeloženými názvy a také číselníky zemí, jazyků, profesí, věkových hodnocení a poskytovatelů. - [Trendy a seznamy](https://amodb.dev/cs/trending-lists/): API trendů filmů s cestami TMDB v3: denní a týdenní žebříčky a seznamy now playing, popular, top rated a upcoming pro filmy a seriály, cachované 30 minut. - [API klíčových slov](https://amodb.dev/cs/keywords/): API klíčových slov s cestami TMDB v3: dějové štítky filmu nebo seriálu, detail klíčového slova, jeho filmy a kombinace ID s with_keywords v discover. - [Společnosti a televizní sítě](https://amodb.dev/cs/companies-networks/): Produkční společnosti a televizní sítě přes cesty TMDB v3. Přečtěte název, zemi a logo podle ID a filtrujte discover podle ID společnosti nebo sítě. - [Limity požadavků](https://amodb.dev/cs/rate-limits/): amodb omezuje klíč počtem požadavků za minutu v klouzavém okně 60 sekund: 20, 40 nebo 120 podle tarifu. Čtěte hlavičky limitu a řešte 429 pomocí Retry-After. Aktualizováno: 2026-10-18. Source: https://amodb.dev/cs/discover/