# API фільмів для пошуку, деталей і рейтингів

> amodb це платний API фільмів на https://api.amodb.dev/3 із тими самими шляхами та JSON, що й TMDB v3. Знайдіть назву через /search/movie, а потім прочитайте фільм з append_to_response, щоб отримати акторів, трейлери та рейтинги одним запитом. Відповіді доступні 14 мовами, від 20 запитів на хвилину.

## API фільмів, що розуміє TMDB v3 і OMDb

amodb це незалежний API фільмів. Він працює за тим самим протоколом, що й TMDB v3 та OMDb, тож клієнт, написаний для будь-якого з них, працює після зміни базового URL на `https://api.amodb.dev/3` (або `https://api.amodb.dev/omdb/` для викликів у стилі OMDb). Ви знаходите фільм через `/search/movie`, а потім читаєте його через `/movie/{movie_id}` і `append_to_response`.

Що ви отримуєте:

- JSON у форматі TMDB v3 з тими самими шляхами й параметрами запиту.
- Назви й описи 14 мовами, які вибираються через `language`.
- Акторський склад, знімальна група, трейлери, ключові слова, зображення й дати виходу через `append_to_response`.
- Рейтинги з IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB, якщо вони відомі.
- Постери з `https://img.amodb.dev/t/p/{size}/{file}` без ключа.

## Які дані ви отримуєте

| Що потрібно                        | Запит                        | Примітки                                                                                                       |
| ---------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Знайти фільм за назвою             | `GET /3/search/movie?query=` | Сторінками, до 20 результатів на сторінці, edge-кеш 10 хвилин. Дивіться [пошук](https://amodb.dev/uk/search/). |
| Основний запис                     | `GET /3/movie/{movie_id}`    | Назви, опис, тривалість, жанри, дата виходу. Дивіться [фільми](https://amodb.dev/uk/movies/).                  |
| Акторський склад і знімальна група | `append_to_response=credits` | Поля описано на сторінці [акторський склад і знімальна група](https://amodb.dev/uk/credits/).                  |
| Трейлери                           | `append_to_response=videos`  | Повертає масив `results` з `key`, `site` і `type`.                                                             |
| Оцінки                             | `append_to_response=ratings` | П'ять джерел, кожне `{ value, votes }` або null. Дивіться [рейтинги](https://amodb.dev/uk/ratings/).           |
| Відповідь у стилі OMDb             | `GET /omdb/?t=Inception`     | Ті самі поля тіла, що й в OMDb. Дивіться [ендпоінт OMDb](https://amodb.dev/uk/omdb-endpoint/).                 |

## Почніть за 3 кроки

1. Оберіть тариф на сторінці [ціни](https://amodb.dev/uk/pricing/). Тарифи відрізняються лише лімітом: 20, 40 або 120 запитів на хвилину.
2. Створіть ключ у кабінеті акаунта. Ключ складається з 32 шістнадцяткових символів у нижньому регістрі.
3. Викличте ендпоінт із ключем у параметрі `api_key` або в заголовку `Authorization: Bearer`. Дивіться [автентифікація](https://amodb.dev/uk/authentication/).

## Приклад запиту

Приклад знаходить Inception за назвою, бере перший збіг і читає фільм з акторами, трейлерами та рейтингами ще одним запитом. Разом це два запити.

```bash
# 1. find the id
curl -s "https://api.amodb.dev/3/search/movie?query=inception&language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

# 2. read the movie with extras
curl -s "https://api.amodb.dev/3/movie/27205?language=en-US&append_to_response=credits,videos,ratings" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function get(path, params) {
  const res = await fetch(`${base}${path}?${new URLSearchParams(params)}`, { headers });
  if (res.status === 429) {
    throw new Error(`Over the limit, retry in ${res.headers.get('Retry-After')} s`);
  }
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  return res.json();
}

const found = await get('/search/movie', { query: 'inception', language: 'en-US' });
if (!found.results.length) throw new Error('No match');

const movie = await get(`/movie/${found.results[0].id}`, {
  language: 'en-US',
  append_to_response: 'credits,videos,ratings',
});
const director = movie.credits.crew.find((c) => c.job === 'Director');
console.log(movie.title, movie.release_date, movie.runtime, director?.name);
console.log('IMDb', movie.ratings.imdb?.value);
```

Скорочена відповідь. Збережено лише частину полів запису фільму, `credits` обрізано до одного актора й режисера, а блок `videos` пропущено.

```json
{
  "genres": [
    {
      "id": 12,
      "name": "Adventure"
    },
    {
      "id": 28,
      "name": "Action"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "id": 27205,
  "imdb_id": "tt1375666",
  "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
  "release_date": "2010-07-15",
  "runtime": 148,
  "title": "Inception",
  "credits": {
    "cast": [
      {
        "adult": false,
        "gender": 2,
        "id": 6193,
        "known_for_department": "Acting",
        "name": "Leonardo DiCaprio",
        "original_name": "Leonardo DiCaprio",
        "popularity": 9.3213,
        "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "character": "Dom Cobb",
        "credit_id": "52fe4534c3a368484e04de03",
        "order": 0
      }
    ],
    "crew": [
      {
        "adult": false,
        "gender": 2,
        "id": 525,
        "known_for_department": "Directing",
        "name": "Christopher Nolan",
        "original_name": "Christopher Nolan",
        "popularity": 8.578,
        "profile_path": "/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
        "credit_id": "5e83ac2ee33f830018359a00",
        "department": "Directing",
        "job": "Director"
      }
    ]
  },
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2877173
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 74,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 86,
      "votes": null
    },
    "tmdb": {
      "value": 8.373,
      "votes": 40457
    }
  }
}
```

## Способи знайти фільм

Оберіть запит, який відповідає тому, що у вас уже є.

| З чого ви починаєте                 | Запит                                           | Результат                                                      |
| ----------------------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
| Назва, введена користувачем         | `GET /3/search/movie?query=`                    | Масив `results` з `id`, `title`, `release_date`, `poster_path` |
| IMDb id, наприклад `tt0133093`      | `GET /3/find/tt0133093?external_source=imdb_id` | Масив `movie_results`                                          |
| Числовий id фільму, наприклад `603` | `GET /3/movie/603`                              | Повний запис                                                   |
| Наявний клієнт OMDb                 | `GET /omdb/?i=tt0133093`                        | Тіло OMDb з `Title`, `Year`, `Ratings`                         |

Зберігайте обидва id. Числовий `id` є ключем для всіх інших запитів, а `imdb_id` поєднує ваші дані з іншими системами. Правила пошуку описано на сторінці [пошук за зовнішнім ID](https://amodb.dev/uk/find-by-external-id/).

## Порожні поля та невдалі запити

У реальних даних про фільми є прогалини, тож напишіть код показу з їх урахуванням. Пошук без збігів не є помилкою: він повертає HTTP 200 з порожнім масивом `results`. Невідомий id це помилка.

| Випадок                   | Що ви бачите               | Що робити                                    |
| ------------------------- | -------------------------- | -------------------------------------------- |
| Немає збігів у пошуку     | 200 і `"results": []`      | Покажіть «збігів немає», не повторюйте запит |
| Невідомий id фільму       | 404 із `status_code` 34    | Видаліть id зі свого списку                  |
| Відсутній або хибний ключ | 401 із `status_code` 7     | Зупиніться й виправте ключ                   |
| Порожній `overview`       | Порожній рядок             | Повторіть запит із `language=en-US`          |
| Невідома оцінка           | `null` всередині `ratings` | Сховайте цей значок                          |
| Немає дати виходу         | Порожній `release_date`    | Поставте фільм у кінець сортування           |

Повний список помилок на сторінці [помилки](https://amodb.dev/uk/errors/).

## Як вкластися в ліміт запитів

Пошук і запит деталей коштують по одному запиту. При 20 запитах на хвилину це десять пошуків назви на хвилину, при 120 запитах на хвилину шістдесят. Влучання в edge-кеш також враховується, бо перевірка ключа й ліміт запитів виконуються перед кешем. Ведіть власний кеш для повторних запитів і читайте `X-RateLimit-Remaining`, щоб бачити, скільки лишилося від хвилини. Отримавши 429, зачекайте стільки секунд, скільки вказано в `Retry-After`. Ліміти за тарифами на сторінці [ліміти запитів](https://amodb.dev/uk/rate-limits/).

## Порівняння

| Можливість                                    | Скрапінг сторінок власноруч           | Безкоштовний API метаданих                              | amodb                                               |
| --------------------------------------------- | ------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- |
| Формат відповіді                              | HTML, який треба розбирати            | JSON                                                    | JSON у форматі TMDB v3                              |
| Стабільність схеми                            | Ламається при зміні розмітки сторінки | Визначає провайдер                                      | Фіксовані шляхи й поля, можуть з'являтися нові поля |
| Умови доступу                                 | Діють умови кожного сайту             | Безкоштовний тариф з умовами використання, перевірте їх | Платно, передплата, без безкоштовного тарифу        |
| Ліміт запитів                                 | Нічого, на що можна спертися          | Визначає провайдер                                      | 20, 40 або 120 запитів на хвилину на ключ           |
| Рейтинги з кількох джерел                     | Один скрапер на сайт                  | По-різному, дивіться документацію                       | `ratings` у тому самому запиті, null, коли невідомо |
| Мови                                          | Те, що пропонує кожна сторінка        | По-різному                                              | 14, вибираються через `language`                    |
| Повторне використання клієнтів TMDB v3 і OMDb | Ні                                    | Лише якщо той самий протокол                            | Так, змініть базовий URL                            |

## Ціни

Доступ передплачується на 1, 3, 6, 12 або 24 місяці зі знижками 0, 10, 20, 30 і 40 відсотків за довші періоди. Автоматичного поновлення та безкоштовного тарифу немає. Кожен тариф отримує всі дані, а тарифи відрізняються лише лімітом: 20, 40 або 120 запитів на хвилину. Оберіть один на сторінці [ціни](https://amodb.dev/uk/pricing/) і зробіть перший запит за кілька хвилин.

## Запитання й відповіді

### Чи сумісний цей API фільмів з TMDB?

Так, для ендпоінтів читання, потрібних застосунку про фільми. Шляхи, параметри запиту та JSON збігаються з TMDB v3 на https://api.amodb.dev/3, тож ви змінюєте базовий URL і використовуєте ключ amodb. Методи запису для акаунта, сесій, оцінок і списків повертають 405 із status_code 37. Стрічки changes, а також aggregate_credits, credit і пошук рецензій повертають 404.

### Чи можна знайти фільм за IMDb id?

Так. Викличте /3/find/tt0133093?external_source=imdb_id і прочитайте movie_results або скористайтеся ендпоінтом у стилі OMDb за адресою /omdb/?i=tt0133093. Обидва приймають той самий ключ, що й виклики у стилі TMDB.

### Скільки запитів потрібно для сторінки фільму?

Щонайбільше два: один пошук, щоб отримати id, і один виклик /movie/{id} з append_to_response=credits,videos,ratings. Якщо id уже збережено, достатньо одного запиту.

### Якими мовами відповідає API фільмів?

Чотирнадцятьма: англійською, російською, українською, білоруською, китайською, португальською, болгарською, івритом, чеською, румунською, французькою, польською, італійською та іспанською. Передайте у language тег TMDB, наприклад pt-BR. Будь-який інший тег відкочується на англійську.

### Чи є безкоштовний тариф або пробний період?

Ні. Доступ передплачується на 1, 3, 6, 12 або 24 місяці зі знижками 0, 10, 20, 30 і 40 відсотків. Автоматичного поновлення немає. Тарифи з 20, 40 і 120 запитами на хвилину наведено на сторінці цін.

## Пов'язані сторінки

- [API деталей фільму](https://amodb.dev/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами.
- [API пошуку](https://amodb.dev/uk/search/): API пошуку з тими самими шляхами та JSON, що в TMDB v3. Шукайте фільми, серіали, персон, колекції, компанії та ключові слова за текстом, з фільтром за роком.
- [Рейтинги фільмів і серіалів](https://amodb.dev/uk/ratings/): API рейтингів фільмів повертає оцінки IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB для фільму чи серіалу одним викликом, з null для невідомих джерел.
- [Пошук за зовнішнім ID](https://amodb.dev/uk/find-by-external-id/): Знайдіть фільм, серіал чи персону за id IMDb, TVDB, Wikidata або Kinopoisk через find TMDB, а також прочитайте зовнішні id і факти Wikidata про проєкт.
- [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини.
- [Альтернатива TMDB API](https://amodb.dev/uk/tmdb-api-alternative/): Шукаєте альтернативу TMDB API? Перевірте умови, ліміти, мови й рейтинги та перейдіть на платний API, що зберігає більшість шляхів читання TMDB v3 і JSON.

Оновлено: 2026-10-18. Source: https://amodb.dev/uk/movie-api/