# API пошуку > Эндпоінты пошуку ператвараюць тэкставы запыт у id. GET /3/search/movie знаходзіць фільмы, а суседнія шляхі шукаюць серыялы, персон, калекцыі, кампаніі і ключавыя словы або ўсе медыя адразу праз multi. JSON адпавядае TMDB v3, вынікі вяртаюцца па 20 на старонку, а edge кэшуе запыт на 10 хвілін. ## Эндпоінт `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Адказ: ```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": 40461 }, { "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 } ``` ## Пошук фільмаў `GET /3/search/movie` прымае тэкставы запыт і вяртае пастаронкавы спіс фільмаў, якія супадаюць, найлепшае супадзенне першым. Выкарыстоўвайце яго, каб ператварыць тое, што ўвёў карыстальнік, у id фільма, а потым выклікайце [дэталі фільма](https://amodb.dev/be/movies/) з гэтым id. У прыкладзе шукаецца Inception з абмежаваннем па 2010 годзе і друкуюцца id, назва і дата выхаду. ```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) } } ``` ### Параметры | Параметр | Дзе | Абавязковы | Апісанне | | ---------------------- | ----- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | запыт | так | Тэкст для пошуку. Закадуйце яго для URL: прабелы становяцца `%20` або `+`. | | `api_key` | запыт | адзін з двух | Ваш ключ. Выкарыстоўвайце яго або загаловак `Authorization: Bearer`. | | `year` | запыт | не | Чатырохзначны год. Пакідае фільмы з любой датай выхаду ў гэтым годзе ў любой краіне. | | `primary_release_year` | запыт | не | Чатырохзначны год. Супадае толькі з асноўнай датай выхаду, таму можа вярнуць менш фільмаў, чым `year`. | | `region` | запыт | не | Двухлітарны код краіны вялікімі літарамі, напрыклад `US`. Замяняе `release_date` датай у гэтай краіне, калі яна вядомая. Фільмы не выдаляе. | | `include_adult` | запыт | не | Прымаецца і ігнаруецца. Фільмы для дарослых ніколі не вяртаюцца. | | `language` | запыт | не | Тэг TMDB, напрыклад `en-US` або `it-IT`. Падтрымліваюцца 14 базавых моў, усё астатняе замяняецца англійскай. Па змаўчанні `en-US`. | | `page` | запыт | не | Нумар старонкі ад 1 да 500. Па змаўчанні 1. | ### Палі адказу | Поле | Тып | Заўвагі | | ------------------------------------------ | ----------------- | --------------------------------------------------------------------------------------- | | `page` | цэлы лік | Старонка, якую вы запыталі. | | `results` | масіў | Да 20 запісаў, найлепшае супадзенне першым. | | `total_pages`, `total_results` | цэлы лік | Памер набору вынікаў для гэтага запыту. Абмежаваны 500 старонкамі і 10000 вынікаў. | | `id` | цэлы лік | Id фільма для эндпоінта дэталяў. | | `title`, `original_title` | радок | Лакалізаваная і арыгінальная назва. | | `original_language` | радок | Двухлітарны код мовы, на якой зняты фільм. | | `overview` | радок | Лакалізаваны тэкст, пусты, калі перакладу няма. | | `release_date` | радок | `YYYY-MM-DD`, пусты для фільмаў без даты. | | `genre_ids` | масіў цэлых лікаў | Id жанраў, а не назвы. Супастаўце іх праз [жанры](https://amodb.dev/be/genres/). | | `poster_path`, `backdrop_path` | радок або null | Дадайце да `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | лік | Значэнні папулярнасці і ацэнкі. | | `adult`, `video` | лагічнае значэнне | `adult` заўсёды `false`. `video` роўна `true` для запісаў, пазначаных як відэаматэрыял. | ### Прыклад адказу ```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 } ``` Адказ утрымлівае ўсе тры супадзенні. Ён атрыманы з жывога API, скарочаны толькі доўгія радкі `overview`. ## Іншыя эндпоінты пошуку Кожны шлях ніжэй мае агульную аснову `https://api.amodb.dev/3`, патрабуе `query` і вяртае тую ж структуру `page`, `results`, `total_pages` і `total_results`. Кожны таксама прымае `page` ад 1 да 500. `include_adult` прымаецца ўсімі і ігнаруецца. | Метад і шлях | Што знаходзіць | Дадатковыя параметры | Палі запісу | | ------------------------ | ------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Серыялы | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Персоны | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Фільмы, серыялы і персоны разам | `language` | `media_type` плюс палі адпаведнага тыпу | | `GET /search/collection` | Калекцыі фільмаў | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Вытворчыя кампаніі | няма | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Ключавыя словы | няма | `id`, `name` | Для серыялаў `first_air_date_year` пакідае серыялы, дата першага эфіру якіх прыпадае на гэты год, а `year` пакідае таксама старэйшыя серыялы, што выходзілі ў гэтым годзе. Пошук `the` з `year=2010` вяртае The Simpsons, які ўпершыню выйшаў у 1989 годзе, а той жа пошук з `first_air_date_year=2010` яго не вяртае. Калі адправіць абодва параметры, павінны супасці абодва. Запісы персон нясуць да 3 назваў у `known_for`, кожная з `media_type`. `/search/multi` ігнаруе `year`. Знойдзеныя тут сутнасці апісаны далей на старонках [серыялы](https://amodb.dev/be/tv-series/), [персоны](https://amodb.dev/be/people/), [калекцыі](https://amodb.dev/be/collections/), [кампаніі і тэлеканалы](https://amodb.dev/be/companies-networks/) і [ключавыя словы](https://amodb.dev/be/keywords/). ### Сумесны пошук multi `media_type` мае значэнне `movie`, `tv` або `person` і падказвае, якія палі чакаць. Запісы фільмаў нясуць `title`, а запісы серыялаў і персон нясуць `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Памылкі `/search/tv` і `/search/person` на запыт без супадзенняў адказваюць HTTP 200, пустым масівам `results` і `total_results`, роўным 0. Зараз `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` і `/search/collection` у такім жа выпадку адказваюць HTTP 500 і `status_code` 11. Лічыце 500 на гэтых шляхах адсутнасцю вынікаў, калі толькі ён не паўтараецца для запытаў, пра якія вы ведаеце, што яны павінны даваць вынікі. | HTTP | status_code | Калі | | ---- | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | Ключ адсутнічае або няправільны. | | 402 | 36 | Тэрмін дзеяння плана скончыўся. | | 405 | 37 | Вы выклікалі метад запісу. | | 429 | 25 | Перавышаны ліміт запытаў у хвіліну. Пачакайце `Retry-After` секунд. | | 500 | 11 | Запыт movie, multi, keyword, company або collection, што нічога не знаходзіць, або `page` па-за дыяпазонам ад 1 да 500. | | 504 | 24 | Бэкенд не адказаў своечасова. Паўтарыце запыт адзін раз. | Поўны спіс гл. на старонцы [памылкі](https://amodb.dev/be/errors/), а акны лімітаў на старонцы [ліміты запытаў](https://amodb.dev/be/rate-limits/). ## Практычныя заўвагі - Edge кэшуе пошук на 10 хвілін і падзяляе копію паміж ключамі. Кожны выклік усё роўна ўлічваецца ў вашых 20, 40 або 120 запытах у хвіліну, бо ліміт запытаў правяраецца да кэшу. - Для поля пошуку пачакайце 300 мс пасля апошняга націску клавішы і скасуйце запыт, які ўжо ляціць. Поле, якое адпраўляе запыт на кожны сімвал, можа за секунды вычарпаць план на 20 запытаў у хвіліну. - Прывядзіце запыт да малых літар і абрэжце прабелы, перш чым выкарыстоўваць яго як ключ кэшу на вашым баку. - Каб знайсці назву па IMDb id, прапусціце пошук і выкарыстоўвайце [пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/). - Id ключавога слова з `/search/keyword` падаецца ў фільтр `with_keywords` на старонцы [пошук па фільтрах](https://amodb.dev/be/discover/), а id кампаніі ў `with_companies`. ## Пытанні і адказы ### Колькі вынікаў вяртае адна старонка пошуку? На старонцы 20 вынікаў, а параметр page прымае значэнні ад 1 да 500. Чытайце total_pages і total_results з адказу, а размытыя запыты звужайце праз year або primary_release_year. ### Ці ўлічваюцца кэшаваныя пошукі ў маім ліміце запытаў? Так. Edge кэшуе пошук на 10 хвілін і падзяляе гэтую копію паміж ключамі, але праверка ключа і ліміту запытаў адбываецца да пошуку ў кэшы, таму кожны выклік лічыцца адзін раз. ### Ці можна шукаць па IMDb id праз гэтыя эндпоінты? Не. Скарыстайцеся GET /3/find/{external_id} з external_source=imdb_id. Ён вяртае movie_results, tv_results і person_results для гэтага id і апісаны на старонцы пошуку па вонкавым ідэнтыфікатары. ### На якой мове вынікі? Параметр language вызначае назвы і апісанні, па змаўчанні en-US. Тэгі па-за межамі 14 базавых моў замяняюцца англійскай. Арыгінальныя назвы застаюцца ў original_title і original_name. ## Звязаныя старонкі - [API дэталяў фільма](https://amodb.dev/be/movies/): API дэталяў фільма з тымі ж шляхамі і JSON, што ў TMDB v3. Адзін фільм па id, а акцёры, рэйтынгі і настрой праз append_to_response, на 14 мовах. - [API серыялаў](https://amodb.dev/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду. - [API дэталяў персоны](https://amodb.dev/be/people/): API дэталяў персоны з тымі ж шляхамі і JSON, што ў TMDB v3. Акцёр ці член групы па id з біяграфіяй, фільмаграфіяй, вонкавымі id і спісам папулярных. - [Discover API](https://amodb.dev/be/discover/): Discover API з фільтрамі TMDB v3. Спіс фільмаў і серыялаў па жанры, акцёрах, кампаніі, ключавым слове, годзе, рэйтынгу і працягласці з сартаваннем. - [Пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/): Шукайце фільм, серыял або персону па IMDb, TVDB, Wikidata ці Kinopoisk id праз эндпоінт find TMDB і чытайце вонкавыя id і факты Wikidata для назвы. - [Ліміты запытаў](https://amodb.dev/be/rate-limits/): amodb абмяжоўвае ключ па запытах у хвіліну ў слізгальным акне 60 секунд: 20, 40 або 120 па плане. Чытайце загалоўкі лімітаў і апрацоўвайце 429 праз Retry-After. Абноўлена: 2026-10-18. Source: https://amodb.dev/be/search/