# Альтэрнатыва IMDb API

> У IMDb няма бясплатнага агульнага REST API: яго некамерцыйныя наборы даных гэта файлы для загрузкі, а камерцыйны доступ ліцэнзуецца. amodb гэта платнае JSON API, дзе вы шукаеце назву па IMDb id, чытаеце рэйтынг IMDb і колькасць галасоў, калі яны вядомыя, і атрымлівайце акцёраў, выявы і трэйлеры з адным ключом.

## Даныя IMDb праз REST: кароткі адказ

У IMDb няма бясплатнага агульнага REST API. Яго некамерцыйныя наборы даных гэта файлы для загрузкі, а камерцыйны доступ ліцэнзуецца, таму бягучыя ўмовы глядзіце ў іх дакументацыі. Калі вы хочаце выклікаць HTTP-эндпоінт з IMDb id і атрымліваць JSON, amodb робіць гэта на платным плане. Калі ваш кантракт патрабуе даных, ліцэнзаваных самім IMDb, гэтае пагадненне заключаецца з IMDb, і amodb яго не замяняе.

## Спосабы выкарыстаць IMDb id у amodb

Пяць выклікаў закрываюць большасць патрэб. Кожны пачынаецца з id, які ў вас ужо ёсць, або заканчваецца ім.

| Што ў вас ёсць або што трэба | Выклік                                          | Што вы атрымліваеце                                    |
| ---------------------------- | ----------------------------------------------- | ------------------------------------------------------ |
| Назва па IMDb id             | `GET /3/find/tt0137523?external_source=imdb_id` | Масівы `movie_results`, `tv_results`, `person_results` |
| IMDb id фільма               | `GET /3/movie/550`, поле `imdb_id`              | `tt0137523` для Fight Club                             |
| IMDb id серыяла              | `GET /3/tv/1396/external_ids`                   | `imdb_id` побач з id TVDB                              |
| Ацэнка IMDb                  | `GET /3/movie/550/ratings`                      | `imdb` як `value` і `votes` або null                   |
| Запіс у стылі OMDb           | `GET /omdb/?i=tt0137523`                        | `imdbRating`, `imdbVotes`, `imdbID`                    |

Кожны радок працуе з тым жа ключом. Рэйтынгі апісаны на старонцы [рэйтынгі](https://amodb.dev/be/ratings/), а пошук па id на старонцы [пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/).

## Як прачытаць ацэнку IMDb

Эндпоінт рэйтынгаў вяртае ацэнку і колькасць галасоў разам. Гэта сапраўдны адказ для Fight Club (id 550). Ацэнкі з часам мяняюцца.

```json
{
  "id": 550,
  "imdb": {
    "value": 8.8,
    "votes": 2669989
  },
  "kinopoisk": {
    "value": 8.7,
    "votes": null
  },
  "metacritic": {
    "value": 67,
    "votes": null
  },
  "rotten_tomatoes": {
    "value": 81,
    "votes": null
  },
  "tmdb": {
    "value": 8.437,
    "votes": 33039
  }
}
```

Для IMDb `value` дадзена па шкале ад 0 да 10 з адным знакам пасля коскі. Паказвайце колькасць галасоў побач і нічога не адлюстроўвайце, калі аб’ект роўны `null`. У гэтым адказе галасы нясуць толькі IMDb і TMDB. `votes` можа быць `null` для любой крыніцы, таму правярайце яго перад паказам. Кэшаваны адказ застаецца дзейсным 6 гадзін на edge, таму больш частыя запыты нічога не даюць.

## Параўнанне магчымасцей

| Магчымасць               | IMDb                                                                               | amodb                                                    |
| ------------------------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Мадэль цэнаўтварэння     | Ліцэнзаваны камерцыйны доступ, глядзіце іх дакументацыю                            | З аплатай наперад, ад 1 да 24 месяцаў                    |
| Бясплатны тарыф          | Няма бясплатнага агульнага REST API                                                | Няма, пробнага перыяду таксама няма                      |
| Аўтэнтыфікацыя           | Глядзіце іх дакументацыю                                                           | Параметр запыту `api_key` або загаловак Bearer           |
| Фармат адказу            | Файлы набораў даных для загрузкі, пра ліцэнзаваныя стужкі глядзіце іх дакументацыю | JSON                                                     |
| Мовы                     | Глядзіце іх дакументацыю                                                           | 14 моў інтэрфейсу                                        |
| Фільмы                   | Пра палі глядзіце іх дакументацыю                                                  | Дэталі, акцёры, выявы, відэа                             |
| Серыялы                  | Пра палі глядзіце іх дакументацыю                                                  | Серыялы, сезоны, эпізоды                                 |
| Персоны                  | Пра палі глядзіце іх дакументацыю                                                  | Профілі, фільмаграфія, выявы                             |
| Выявы                    | Глядзіце іх дакументацыю                                                           | `img.amodb.dev`, ключ не патрэбны                        |
| Рэйтынгі                 | Уласная ацэнка, пра доступ глядзіце іх дакументацыю                                | Пяць крыніц, сярод іх IMDb, калі вядомыя                 |
| Ліміт запытаў            | Глядзіце іх дакументацыю                                                           | 20, 40 або 120 запытаў у хвіліну                         |
| Камерцыйнае выкарыстанне | Ліцэнзавана, глядзіце іх дакументацыю                                              | Платныя планы, гл. [цэны](https://amodb.dev/be/pricing/) |
| Сумяшчальнасць           | Уласныя фарматы, глядзіце іх дакументацыю                                          | Чытанне TMDB v3 і пратакол OMDb                          |

## Чым адрозніваецца amodb

Вы выклікаеце эндпоінт, а не разбіраеце файл. Адзін запыт вяртае назву з акцёрамі, трэйлерамі і рэйтынгамі праз `append_to_response`, а форма адпавядае TMDB v3, таму існуючыя бібліятэкі кліентаў працуюць. Той жа ключ абслугоўвае эндпоінт у стылі OMDb, які трымае ў працы старэйшы код, што чытае `imdbRating`.

Блок рэйтынгаў ёсць фіксаваным аб’ектам з пяццю ключамі. Невядомая крыніца роўная `null`, а не адсутнічае як ключ, таму код, які чытае `ratings.imdb`, не патрабуе праверкі існавання бацькоўскага аб’екта. Побач са значэннем можа стаяць колькасць галасоў, што дазваляе схаваць ацэнку, заснаваную на невялікай колькасці галасоў. Яна таксама можа быць `null`, як у трох з пяці крыніц у прыкладзе вышэй.

## Дзе IMDb падыходзіць лепш

- **Крыніца ацэнкі.** IMDb публікуе свае рэйтынгі першым. amodb вяртае значэнне толькі тады, калі яно вядомае, таму новая або малавядомая назва можа вярнуцца з `null`.
- **Функцыі сайта.** Рэцэнзіі, спісы і спісы жадання карыстальнікаў жывуць на сайце IMDb. amodb гэта API метаданых і акаўнтаў карыстальнікаў не мае.
- **Ліцэнзаваныя даныя.** Калі партнёр або кантракт патрабуе даных, ліцэнзаваных IMDb, іх можа даць толькі IMDb.
- **Аўтаномны аналіз.** Файлы некамерцыйных набораў даных падыходзяць для масавых даследаванняў на вашай машыне. Умовы глядзіце ў іх дакументацыі.

## Міграцыя на amodb

Хутчэй за ўсё ў вас ёсць спіс IMDb id. Адзін раз супастаўце кожны з id amodb, захавайце пару і потым выклікайце дэталі па лікавым id.

```bash
curl -s "https://api.amodb.dev/3/find/tt0133093?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```python
import os
import requests

KEY = os.environ["AMODB_KEY"]
imdb_ids = ["tt0137523", "tt0133093", "tt1375666"]

for imdb_id in imdb_ids:
    r = requests.get(
        f"https://api.amodb.dev/3/find/{imdb_id}",
        params={"external_source": "imdb_id"},
        headers={"Authorization": f"Bearer {KEY}"},
        timeout=10,
    )
    r.raise_for_status()
    hits = r.json()["movie_results"]
    print(imdb_id, hits[0]["id"] if hits else None)
```

Тры id вышэй адпавядаюць 550, 603 і 27205, гэта Fight Club, The Matrix і Inception. Id серыяла, напрыклад `tt0903747`, прыходзіць у `tv_results`, дзе Breaking Bad мае id 1396. Пусты масіў азначае, што для гэтага id супадзенне не знойдзена.

Рэгулюйце тэмп цыкла. Кожны id ёсць адным запытам, а 429 уключае загаловак `Retry-After` з колькасцю секунд чакання. Іншыя коды гл. на старонцы [памылкі](https://amodb.dev/be/errors/).

### Як надзейна захоўваць id

- Захоўвайце IMDb id як радкі. Яны пачынаюцца з `tt` і маюць пачатковыя нулі, як у `tt0137523`, а лікавы тып гэтыя нулі губляе.
- Захоўвайце IMDb id і id amodb парай. Любы з іх зноў знаходзіць назву.
- Чытайце `tv_results` для серыялаў і `movie_results` для фільмаў. Адзін id звычайна запаўняе адзін масіў і пакідае астатнія пустымі.
- Далей запытвайце дэталі па id amodb, бо выклік дэталяў можа несці акцёраў, трэйлеры і рэйтынгі праз `append_to_response`.

## Цэны

Абярыце адзін з трох планаў на 20, 40 або 120 запытаў у хвіліну і заплаціце наперад за 1, 3, 6, 12 або 24 месяцы. Доўгія перыяды даюць зніжку 10, 20, 30 або 40 працэнтаў. Усе планы вяртаюць тыя ж даныя, нічога не прадаўжаецца само, і бясплатнага тарыфа няма. Сумы гл. на старонцы [цэны](https://amodb.dev/be/pricing/).

## Пытанні і адказы

### Ці прапануе IMDb бясплатнае REST API?

У IMDb няма бясплатнага агульнага REST API. Яго некамерцыйныя наборы даных гэта файлы для загрузкі, а камерцыйны доступ ліцэнзуецца. Бягучыя ўмовы, фарматы і палі глядзіце ў іх дакументацыі, перш чым на іх разлічваць.

### Ці можна знайсці назву па яе IMDb id у amodb?

Так. Выклічце /3/find/tt0137523 з external_source=imdb_id і прачытайце movie_results, tv_results або person_results. Эндпоінт у стылі OMDb таксама прымае параметр i з IMDb id.

### Ці заўсёды ёсць рэйтынг IMDb?

Не. Аб’ект ratings заўсёды мае пяць ключоў imdb, kinopoisk, metacritic, rotten_tomatoes і tmdb, але кожны роўны null, калі ацэнка невядомая. Апрацуйце null, перш чым паказваць лік.

### Ці атрымліваю я рэцэнзіі і спісы карыстальнікаў IMDb?

Не. amodb вяртае IMDb id і ацэнку IMDb з колькасцю галасоў, калі яны вядомыя. Рэцэнзіі, спісы і спісы жадання карыстальнікаў IMDb ён не захоўвае. Эндпоінт рэцэнзій у стылі TMDB адказвае 200, і для большасці назваў вяртае пусты спіс.

### Колькі часу зойме супастаўленне спісу IMDb id?

Адзін запыт find на кожны id. Спіс з 500 id патрабуе 500 запытаў, таму на плане з 20 запытамі ў хвіліну гэта каля 25 хвілін. Захавайце вынік, бо супастаўленне рэдка змяняецца.

## Звязаныя старонкі

- [Пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/): Шукайце фільм, серыял або персону па IMDb, TVDB, Wikidata ці Kinopoisk id праз эндпоінт find TMDB і чытайце вонкавыя id і факты Wikidata для назвы.
- [Рэйтынгі фільмаў і серыялаў](https://amodb.dev/be/ratings/): API рэйтынгаў фільмаў вяртае ацэнкі IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB для назвы адным выклікам, з null для крыніцы, якая невядомая.
- [Эндпоінт, сумяшчальны з OMDb](https://amodb.dev/be/omdb-endpoint/): Эндпоінт, сумяшчальны з OMDb API, па адрасе api.amodb.dev/omdb/. Пошук па i або t, спіс праз s, масіў Ratings. Змяніце базавы URL, і кліент працуе далей.
- [Альтэрнатыва OMDb API](https://amodb.dev/be/omdb-api-alternative/): Дайшлі да штодзённага ліміту OMDb або патрэбна болей за адзін запіс за выклік? amodb адказвае на запыты ў стылі OMDb і дае эндпоінты TMDB v3 з тым жа ключом.
- [Аўтэнтыфікацыя](https://amodb.dev/be/authentication/): Як перадаваць ключ amodb: api_key у запыце, загаловак Authorization Bearer або apikey для выклікаў OMDb. Фармат ключа, захоўванне, замена і памылкі 401.
- [Ліміты запытаў](https://amodb.dev/be/rate-limits/): amodb абмяжоўвае ключ па запытах у хвіліну ў слізгальным акне 60 секунд: 20, 40 або 120 па плане. Чытайце загалоўкі лімітаў і апрацоўвайце 429 праз Retry-After.

Абноўлена: 2026-10-18. Source: https://amodb.dev/be/imdb-api-alternative/