# 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/ru/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` | query | да | Текст для поиска. Закодируйте его для URL: пробелы превращаются в `%20` или `+`. | | `api_key` | query | один из двух | Ваш ключ. Используйте его или заголовок `Authorization: Bearer`. | | `year` | query | нет | Год из четырех цифр. Оставляет фильмы с любой датой выхода в этом году, в любой стране. | | `primary_release_year` | query | нет | Год из четырех цифр. Сравнивается только с основной датой выхода, поэтому может вернуть меньше тайтлов, чем `year`. | | `region` | query | нет | Код страны из 2 букв в верхнем регистре, например `US`. Заменяет `release_date` датой в этой стране, если она известна. Тайтлы не убирает. | | `include_adult` | query | нет | Принимается и игнорируется. Фильмы для взрослых не возвращаются никогда. | | `language` | query | нет | Тег TMDB, например `en-US` или `it-IT`. Обслуживаются 14 базовых языков, остальные откатываются на английский. По умолчанию `en-US`. | | `page` | query | нет | Номер страницы от 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/ru/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/ru/tv-series/), [люди](https://amodb.dev/ru/people/), [коллекции](https://amodb.dev/ru/collections/), [компании и телесети](https://amodb.dev/ru/companies-networks/) и [ключевые слова](https://amodb.dev/ru/keywords/). ### Мультипоиск `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/ru/errors/), а окна лимитов на странице [лимиты запросов](https://amodb.dev/ru/rate-limits/). ## Практические советы - Edge кэширует поиск на 10 минут и делит копию между ключами. Каждый вызов все равно учитывается в ваших 20, 40 или 120 запросах в минуту, потому что лимит запросов проверяется раньше кэша. - Для поля поиска ждите 300 мс после последнего нажатия клавиши и отменяйте уже отправленный запрос. Поле, которое отправляет запрос на каждую клавишу, исчерпает тариф в 20 запросов в минуту за секунды. - Приводите запрос к нижнему регистру и обрезайте пробелы, прежде чем использовать его как ключ кэша у себя. - Чтобы найти тайтл по IMDb ID, пропустите поиск и используйте [поиск по внешнему ID](https://amodb.dev/ru/find-by-external-id/). - ID ключевого слова из `/search/keyword` подставляется в фильтр `with_keywords` в [discover](https://amodb.dev/ru/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 и описан на странице поиска по внешнему ID. ### На каком языке приходят результаты? Параметр language задает язык названий и описаний, по умолчанию en-US. Теги за пределами 14 базовых языков откатываются на английский. Оригинальные названия остаются доступны в original_title и original_name. ## Связанные страницы - [API деталей фильма](https://amodb.dev/ru/movies/): API деталей фильма с теми же путями и JSON, что в TMDB v3. Получите фильм по ID, добавьте актеров, рейтинги и настроения через append_to_response, на 14 языках. - [API сериалов](https://amodb.dev/ru/tv-series/): API сериалов с теми же путями и JSON, что в TMDB v3. Сериал по id с сезонами, телесетями и следующей серией, а также возрастные рейтинги и сервисы просмотра. - [API деталей человека](https://amodb.dev/ru/people/): API деталей человека с теми же путями и JSON, что в TMDB v3. Получайте актера или члена съемочной группы по ID: биография, фильмография, внешние ID, популярные. - [Discover API](https://amodb.dev/ru/discover/): Discover API с фильтрами TMDB v3. Фильмы и сериалы по жанру, актеру, студии, ключевому слову, году, рейтингу, длительности и провайдеру, с сортировкой. - [Поиск по внешнему ID](https://amodb.dev/ru/find-by-external-id/): Найдите фильм, сериал или персону по ID IMDb, TVDB, Wikidata или Kinopoisk через эндпоинт find TMDB, а также прочитайте внешние ID и факты Wikidata о проекте. - [Лимиты запросов](https://amodb.dev/ru/rate-limits/): amodb ограничивает ключ запросами в минуту в скользящем окне 60 секунд: 20, 40 или 120 по тарифу. Читайте заголовки лимита и обрабатывайте 429 с Retry-After. Обновлено: 2026-10-18. Source: https://amodb.dev/ru/search/