# API vyhledávání > Endpointy vyhledávání převádějí textový dotaz na ID. GET /3/search/movie najde filmy a sourozenecké cesty najdou seriály, osoby, kolekce, společnosti a klíčová slova, nebo všechna média najednou přes multi. JSON odpovídá TMDB v3, výsledky jsou stránkované po 20 a edge cachuje dotaz 10 minut. ## Endpoint `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Odpověď: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [ 28, 878, 80 ], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another per...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40459 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [ 16, 28, 53 ], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [ 10402 ], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` ## Hledání filmů `GET /3/search/movie` přijme textový dotaz a vrátí stránkovaný seznam odpovídajících filmů, nejlepší shoda první. Použijte jej k převodu toho, co uživatel napsal, na ID filmu a pak s tímto ID zavolejte [detail filmu](https://amodb.dev/cs/movies/). Příklad hledá Inception omezené na rok 2010 a vypíše ID, název a datum vydání. ```bash curl -sSf --get "https://api.amodb.dev/3/search/movie" \ --data-urlencode "query=inception" \ --data-urlencode "year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' }); const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { results, total_results } = await res.json(); console.log(`${total_results} matches`); for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/search/movie", params={"query": "inception", "year": 2010, "language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() data = r.json() print(data["total_results"], "matches") for m in data["results"][:5]: print(m["id"], m["title"], m["release_date"]) ``` ```php 'inception', 'year' => 2010, '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['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type SearchPage struct { TotalResults int `json:"total_results"` Results []struct { ID int `json:"id"` Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"results"` } func main() { q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/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 SearchPage if err := json.NewDecoder(res.Body).Decode(&p); err != nil { panic(err) } fmt.Println(p.TotalResults, "matches") for _, m := range p.Results { fmt.Println(m.ID, m.Title, m.ReleaseDate) } } ``` ### Parametry | Parametr | Kde | Povinný | Popis | | ---------------------- | ----- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `query` | query | ano | Hledaný text. Zakódujte jej do URL: mezery se změní na `%20` nebo `+`. | | `api_key` | query | jeden ze dvou | Váš klíč. Použijte jej, nebo hlavičku `Authorization: Bearer`. | | `year` | query | ne | Čtyřmístný rok. Ponechá filmy s libovolným datem vydání v tom roce, v jakékoli zemi. | | `primary_release_year` | query | ne | Čtyřmístný rok. Odpovídá jen primárnímu datu vydání, takže může vrátit méně titulů než `year`. | | `region` | query | ne | Dvoupísmenný kód země velkými písmeny, například `US`. Nahradí `release_date` datem v dané zemi, pokud je známo. Tituly neodstraňuje. | | `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 `it-IT`. Podporuje se 14 základních jazyků, cokoli jiného se vrátí k angličtině. 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` | integer | Stránka, o kterou jste požádali. | | `results` | array | Až 20 položek, nejlepší shoda první. | | `total_pages`, `total_results` | integer | Velikost sady výsledků pro tento dotaz. Omezeno na 500 stránek a 10000 výsledků. | | `id` | integer | ID filmu pro endpoint detailu. | | `title`, `original_title` | string | Lokalizovaný a původní název. | | `original_language` | string | Dvoupísmenný kód jazyka, ve kterém byl film natočen. | | `overview` | string | Lokalizovaný text, prázdný, když překlad neexistuje. | | `release_date` | string | `YYYY-MM-DD`, prázdné u titulů bez data. | | `genre_ids` | array of integers | ID žánrů, ne názvy. Převeďte je přes [žánry](https://amodb.dev/cs/genres/). | | `poster_path`, `backdrop_path` | string nebo null | Připojte k `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | number | Hodnoty pořadí a skóre. | | `adult`, `video` | boolean | `adult` je vždy `false`. `video` je `true` u položek označených jako videoobsah. | ### Příklad odpovědi ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [28, 878, 80], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40459 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [16, 28, 53], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [10402], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` Odpověď obsahuje všechny tři shody. Byla stažena z živého API a zkráceny byly jen dlouhé řetězce `overview`. ## Další endpointy hledání Všechny cesty níže sdílejí základ `https://api.amodb.dev/3`, vyžadují `query` a vracejí stejný obal `page`, `results`, `total_pages` a `total_results`. Každá také přijímá `page` od 1 do 500. `include_adult` se přijímá u všech a ignoruje. | Metoda a cesta | Najde | Další parametry | Pole položky | | ------------------------ | -------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Seriály | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Osoby | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Filmy, seriály a osoby dohromady | `language` | `media_type` plus pole daného typu | | `GET /search/collection` | Kolekce filmů | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Produkční společnosti | žádné | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Klíčová slova | žádné | `id`, `name` | U seriálů `first_air_date_year` ponechá seriály, jejichž první vysílání je v daném roce, zatímco `year` ponechá i starší seriály, které v daném roce vysílaly. Hledání `the` s `year=2010` vrátí The Simpsons, které se poprvé vysílaly v roce 1989, a stejné hledání s `first_air_date_year=2010` nikoli. Když pošlete obojí, musí platit obojí. Položky osob nesou až 3 tituly `known_for`, každý s `media_type`. `/search/multi` `year` ignoruje. Nalezené entity pokračují na stránkách [seriály](https://amodb.dev/cs/tv-series/), [osoby](https://amodb.dev/cs/people/), [kolekce](https://amodb.dev/cs/collections/), [společnosti a televizní sítě](https://amodb.dev/cs/companies-networks/) a [klíčová slova](https://amodb.dev/cs/keywords/). ### Multi hledání `media_type` je `movie`, `tv` nebo `person` a říká, jaká pole čekat. Položky filmů nesou `title` a položky seriálů a osob nesou `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Chyby `/search/tv` a `/search/person` odpovídají na dotaz bez shody HTTP 200, prázdným polem `results` a `total_results` rovným 0. V tuto chvíli `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` a `/search/collection` odpovídají na stejný případ HTTP 500 a `status_code` 11. Berte 500 na těchto cestách jako „žádné výsledky“, pokud se neopakuje u dotazů, o kterých víte, že odpovídají. | 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 | Dotaz na film, multi, klíčové slovo, společnost nebo kolekci, který nic nenajde, nebo `page` mimo 1 až 500. | | 504 | 24 | Backend neodpověděl včas. Zkuste to jednou znovu. | Úplný seznam viz [chyby](https://amodb.dev/cs/errors/) a okna viz [limity požadavků](https://amodb.dev/cs/rate-limits/). ## Praktické poznámky - Edge cachuje hledání 10 minut a sdílí kopii mezi klíči. Každé volání se přesto počítá do vašich 20, 40 nebo 120 požadavků za minutu, protože limit se vyhodnocuje před cache. - U vyhledávacího pole počkejte 300 ms po posledním stisku klávesy a rozpracovaný požadavek zrušte. Pole, které odesílá na každou klávesu, může vyčerpat tarif s 20 požadavky za minutu během pár sekund. - Než dotaz použijete jako klíč cache u sebe, převeďte ho na malá písmena a ořízněte. - Titul podle ID z IMDb vyhledáte bez hledání přes [hledání podle externího ID](https://amodb.dev/cs/find-by-external-id/). - ID klíčového slova z `/search/keyword` vstupuje do filtru `with_keywords` v [discover](https://amodb.dev/cs/discover/) a ID společnosti do `with_companies`. ## Otázky a odpovědi ### Kolik výsledků vrací jedna stránka hledání? Každá stránka obsahuje 20 výsledků a parametr page jde od 1 do 500. Z odpovědi čtěte total_pages a total_results a nejasné dotazy zužte přes year nebo primary_release_year. ### Počítají se cachovaná hledání do limitu požadavků? Ano. Edge cachuje hledání 10 minut a sdílí kopii mezi klíči, ale kontrola klíče a limitu proběhne před nalezením v cache, takže každé volání se počítá jednou. ### Mohu s těmito endpointy hledat podle ID z IMDb? Ne. Použijte místo toho GET /3/find/{external_id} s external_source=imdb_id. Vrací movie_results, tv_results a person_results pro dané ID a je popsán na stránce hledání podle externího ID. ### V jakém jazyce jsou výsledky? Parametr language nastavuje názvy a popisy, výchozí en-US. Tagy mimo 14 základních jazyků se vrátí k angličtině. Původní názvy zůstávají dostupné v original_title a original_name. ## Související stránky - [API detailu filmu](https://amodb.dev/cs/movies/): API detailu filmu se stejnými cestami a JSON jako TMDB v3. Načtěte film podle ID, přidejte obsazení, hodnocení a nálady přes append_to_response, 14 jazyků. - [API detailu seriálu](https://amodb.dev/cs/tv-series/): API detailu seriálu se stejnými cestami a JSON jako TMDB v3. Seriál podle ID se sezónami, sítěmi, věkovým hodnocením a poskytovateli streamování. - [API detailu osoby](https://amodb.dev/cs/people/): API detailu osoby se stejnými cestami a JSON jako TMDB v3. Herec či člen štábu podle ID s biografií, filmografií, externími ID a seznamem populárních osob. - [Discover API](https://amodb.dev/cs/discover/): Discover API se stejnými filtry jako TMDB v3. Vypisujte filmy a seriály podle žánru, společnosti, klíčového slova, roku, hodnocení, délky a poskytovatele. - [Hledání podle externího ID](https://amodb.dev/cs/find-by-external-id/): Najděte film, seriál nebo osobu podle ID z IMDb, TVDB, Wikidata nebo Kinopoisk přes endpoint find TMDB a čtěte externí ID a fakta z Wikidata o titulu. - [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/search/