# API пошуку > Ендпоінти пошуку перетворюють текстовий запит на id. GET /3/search/movie шукає фільми, а сусідні шляхи шукають серіали, персон, колекції, компанії та ключові слова або всі медіа одразу через multi. JSON збігається з TMDB v3, результати розбито по 20 на сторінку, а кеш на периферії зберігає запит 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/uk/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` | рядок запиту | ні | Код країни з 2 літер великими літерами, наприклад `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/uk/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/uk/tv-series/), [персони](https://amodb.dev/uk/people/), [колекції](https://amodb.dev/uk/collections/), [компанії та телемережі](https://amodb.dev/uk/companies-networks/) і [ключові слова](https://amodb.dev/uk/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/uk/errors/), а вікна на сторінці [ліміти запитів](https://amodb.dev/uk/rate-limits/). ## Практичні поради - Кеш на периферії зберігає пошук 10 хвилин і ділить копію між ключами. Кожен виклик усе одно враховується у ваших 20, 40 або 120 запитах на хвилину, бо ліміт запитів виконується до кешу. - Для поля пошуку зачекайте 300 мс після останнього натискання клавіші й скасуйте запит, що вже виконується. Поле, яке надсилає запит на кожну клавішу, може вичерпати тариф на 20 запитів на хвилину за лічені секунди. - Переведіть запит у нижній регістр і обріжте пробіли, перш ніж використовувати його як ключ кешу на своєму боці. - Щоб знайти фільм за IMDb id, пропустіть пошук і використайте [пошук за зовнішнім ID](https://amodb.dev/uk/find-by-external-id/). - Id ключового слова з `/search/keyword` підходить до фільтра `with_keywords` у [discover](https://amodb.dev/uk/discover/), а id компанії до `with_companies`. ## Запитання й відповіді ### Скільки результатів повертає одна сторінка пошуку? Кожна сторінка містить 20 результатів, а параметр page змінюється від 1 до 500. Читайте total_pages і total_results з відповіді, а нечіткі запити звужуйте через year або primary_release_year. ### Чи кешовані пошуки теж враховуються в моєму ліміті запитів? Так. Кеш на периферії зберігає пошук 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/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами. - [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги. - [API деталей персони](https://amodb.dev/uk/people/): API деталей персони з тими самими шляхами та JSON, що в TMDB v3. Отримайте актора чи режисера за id: біографія, фільмографія, зовнішні id і список популярних. - [Discover API](https://amodb.dev/uk/discover/): Discover API з тими самими фільтрами, що й у TMDB v3. Фільми та серіали за жанром, акторами, компанією, роком, рейтингом, тривалістю й провайдером. - [Пошук за зовнішнім ID](https://amodb.dev/uk/find-by-external-id/): Знайдіть фільм, серіал чи персону за id IMDb, TVDB, Wikidata або Kinopoisk через find TMDB, а також прочитайте зовнішні id і факти Wikidata про проєкт. - [Ліміти запитів](https://amodb.dev/uk/rate-limits/): amodb обмежує кожен ключ запитами на хвилину в ковзному вікні 60 секунд: 20, 40 або 120 за тарифом. Читайте заголовки ліміту й обробляйте 429 із Retry-After. Оновлено: 2026-10-18. Source: https://amodb.dev/uk/search/