# 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/bg/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/bg/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/bg/tv-series/), [личности](https://amodb.dev/bg/people/), [колекции](https://amodb.dev/bg/collections/), [компании и мрежи](https://amodb.dev/bg/companies-networks/) и [ключови думи](https://amodb.dev/bg/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/bg/errors/) за пълния списък и [лимити на заявките](https://amodb.dev/bg/rate-limits/) за прозорците. ## Практически бележки - Edge кешира търсенето за 10 минути и споделя копието между ключовете. Всяко извикване все пак се брои към вашите 20, 40 или 120 заявки в минута, защото лимитът се проверява преди кеша. - За поле за търсене изчакайте 300 ms след последното натискане на клавиш и отменете заявката, която е в движение. Поле, което изпраща заявка при всеки клавиш, може за секунди да изчерпи план от 20 заявки в минута. - Преобразувайте заявката в малки букви и изрежете интервалите, преди да я ползвате като ключ на кеша при вас. - За търсене на заглавие по IMDb id пропуснете търсенето и ползвайте [търсене по външен идентификатор](https://amodb.dev/bg/find-by-external-id/). - Id на ключова дума от `/search/keyword` захранва филтъра `with_keywords` на страницата [откриване по филтри](https://amodb.dev/bg/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/bg/movies/): API за детайли на филм със същите пътища и JSON като TMDB v3. Един филм по id, а актьори, рейтинги и настроения през append_to_response, на 14 езика. - [API за сериали](https://amodb.dev/bg/tv-series/): API за сериали със същите пътища и JSON като TMDB v3. Сериал по id със сезони, мрежи и следващ епизод, плюс възрастови рейтинги и доставчици за гледане. - [API за детайли на личност](https://amodb.dev/bg/people/): API за детайли на личност със същите пътища и JSON като TMDB v3. Актьор или член на екип по id с биография, филмография, външни id и списък с популярни. - [Discover API](https://amodb.dev/bg/discover/): Discover API със същите филтри като TMDB v3. Списък с филми и сериали по жанр, актьори, компания, ключова дума, година, рейтинг и продължителност със сортиране. - [Търсене по външен идентификатор](https://amodb.dev/bg/find-by-external-id/): Търсете филм, сериал или личност по IMDb, TVDB, Wikidata или Kinopoisk id с ендпойнта find на TMDB и четете външни id и факти от Wikidata за заглавие. - [Лимити на заявките](https://amodb.dev/bg/rate-limits/): amodb ограничава всеки ключ по заявки в минута в плъзгащ се прозорец от 60 секунди: 20, 40 или 120. Заглавки за лимита и обработка на 429 с Retry-After. Обновено: 2026-10-18. Source: https://amodb.dev/bg/search/