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

> Kinopoisk, рускамоўны сайт пра кіно, не публікуе агульнага адкрытага API. Распрацоўшчыкі часта звяртаюцца да знешніх сэрвісаў, таму глядзіце іх дакументацыю. amodb гэта платнае API: яно вяртае рускія назвы з language=ru-RU, знаходзіць назву па Kinopoisk id і ўключае ацэнку Kinopoisk, калі яна вядомая.

## Што можа і чаго не можа даць альтэрнатыва

Kinopoisk, рускамоўны сайт пра кіно, не публікуе агульнага адкрытага API. Распрацоўшчыкі часта карыстаюцца замест гэтага знешнімі сэрвісамі, у кожнага свае ўмовы, таму глядзіце іх дакументацыю. amodb незалежнае API, а не сэрвіс Kinopoisk. Яно закрывае тры патрэбы, якія часта ўзнікаюць у рускамоўных праектах: назвы і апісанні па-руску, пошук па Kinopoisk id і ацэнку Kinopoisk побач з іншымі ацэнкамі, калі яна вядомая.

## Будаўнічыя блокі

| Што вам трэба                      | Як                                             | Што вяртаецца                                      |
| ---------------------------------- | ---------------------------------------------- | -------------------------------------------------- |
| Руская назва і апісанне            | `language=ru-RU` у любым выкліку дэталяў       | `title` па-руску, `original_title` без змен        |
| Назва па Kinopoisk id              | `GET /3/find/361?external_source=kinopoisk_id` | `movie_results` з id 550                           |
| Kinopoisk id назвы                 | `GET /3/movie/550/external_ids`                | `kinopoisk_id` як радок, тут `"361"`               |
| Ацэнка Kinopoisk                   | `GET /3/movie/550/ratings`                     | `kinopoisk` з `value` і `votes` або null           |
| Тэкст па-ўкраінску ці па-беларуску | `language=uk-UA` або `language=be-BY`          | Лакалізаваныя палі, англійская, дзе перакладу няма |

Наступны блок паказвае адзін адказ з дэталямі па-руску з `append_to_response=ratings`. Гэта сапраўдны адказ для Fight Club (id 550), скарочаны да выкарыстоўваных тут палёў, з карацейшым апісаннем.

```json
{
  "id": 550,
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из му...",
  "release_date": "1999-10-15",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб",
  "ratings": {
    "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
    }
  }
}
```

Аб’ект ratings заўсёды пералічвае тыя ж пяць ключоў. Тут ацэнка Kinopoisk роўная 8.7, а яе `votes` роўны `null`, таму колькасць галасоў Kinopoisk нельга лічыць гарантаванай. Падрабязнасці на старонцы [рэйтынгі](https://amodb.dev/be/ratings/).

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

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

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

- **Задакументаваны кантракт.** Шляхі, параметры, целы памылак і ліміты запісаны, і адзін ключ абслугоўвае кожны эндпоінт.
- **Руская побач з іншымі мовамі.** Той жа выклік з іншым значэннем `language` дае тыя ж палі на іншай мове. Гэта зручна, калі вашы чытачы карыстаюцца рускай, украінскай і англійскай.
- **Некалькі ацэнак у адным аб’екце.** Можна паказаць ацэнку Kinopoisk побач з IMDb, Metacritic і Rotten Tomatoes, кожную з `null`, калі яна невядомая.
- **Арыгінальныя назвы захоўваюцца.** `original_title` і `original_name` змяшчаюць назву на мове крыніцы, уключна з японскай і карэйскай, хоць гэта і не мовы інтэрфейсу.

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

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

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

Збярыце Kinopoisk id, якія вы захоўваеце, адзін раз супастаўце іх праз `/3/find` і трымайце побач лікавы id amodb. Пасля гэтага запытвайце дэталі па-руску і чытайце ацэнку з таго ж адказу.

```python
import os
import requests

KEY = os.environ["AMODB_KEY"]
BASE = "https://api.amodb.dev/3"
HEADERS = {"Authorization": f"Bearer {KEY}"}


def get(path, **params):
    r = requests.get(BASE + path, params=params, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


found = get("/find/361", external_source="kinopoisk_id")
movie_id = found["movie_results"][0]["id"]
movie = get(f"/movie/{movie_id}", language="ru-RU", append_to_response="ratings")
kp = movie["ratings"]["kinopoisk"]
print(movie["title"], "/", movie["original_title"])
print("Kinopoisk:", kp["value"] if kp else "not known")
```

Пусты масіў `movie_results` азначае, што для гэтага id няма супадзення. Kinopoisk id серыяла запаўняе замест гэтага `tv_results`, таму чытайце абодва масівы, калі не ведаеце тып. Пры 429 пачакайце `Retry-After` секунд. Спіс моў ёсць на старонцы [мовы](https://amodb.dev/be/languages/), а правілы пошуку на старонцы [пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/).

## Як апрацаваць прабелы ў рускім тэксце

Тэкставае поле можа быць пустым, калі для назвы няма рускага перакладу. Праверце пусты радок і яшчэ раз запытайце гэтую назву з `language=en-US`. Для постэраў з рускімі надпісамі выклічце `/3/movie/550/images?include_image_language=ru,null` і абярыце з `posters`. Значэнне `null` пакідае ў спісе выявы без тэксту. Памеры гл. на старонцы [выявы](https://amodb.dev/be/images-api/).

## Цэны

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

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

### Ці ёсць у Kinopoisk афіцыйнае публічнае API?

Kinopoisk, рускамоўны сайт пра кіно, не публікуе агульнага адкрытага API. Распрацоўшчыкі часта карыстаюцца знешнімі сэрвісамі, у кожнага свае ўмовы. Глядзіце іх дакументацыю, перш чым на іх спадзявацца.

### Як знайсці назву па Kinopoisk id у amodb?

Выклічце /3/find з Kinopoisk id і external_source=kinopoisk_id. Напрыклад, 361 вяртае Fight Club, гэта id 550, а 404900 вяртае Breaking Bad, id 1396. Вынік прыходзіць у movie_results або tv_results у форме TMDB.

### Ці заўсёды вяртаецца рэйтынг Kinopoisk?

Не. Ключ kinopoisk у аб’екце ratings змяшчае value і votes, калі ацэнка вядомая, і null у астатніх выпадках. Значэнне даецца з 10 з адным знакам пасля коскі. votes можа быць null, нават калі value заданае, таму паказвайце яго толькі тады, калі ён ёсць.

### Якія мовы, акрамя рускай, можна запытаць?

Усяго чатырнаццаць, уключна з украінскай і беларускай. Перадайце тэг TMDB, напрыклад uk-UA або be-BY, у параметры language. Непадтрымліваныя тэгі замяняюцца англійскай, а арыгінальныя назвы застаюцца ў original_title.

### Ці атрымліваю я тэкст рэцэнзій Kinopoisk?

Не. amodb вяртае ацэнку Kinopoisk, калі яна вядомая. Тэкст рэцэнзій, спісы і супольнасныя функцыі сайта не ўваходзяць у API, а эндпоінт рэцэнзій у стылі TMDB вяртае пусты спіс для большасці назваў.

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

- [Шматмоўнае API метаданых фільмаў](https://amodb.dev/be/multilingual-movie-metadata-api/): Шматмоўнае API метаданых фільмаў на 14 мовах. Тэгі мовы TMDB, усе пераклады, запасны варыянт на англійскай і правільны вывад іўрыту справа налева.
- [Рэйтынгі фільмаў і серыялаў](https://amodb.dev/be/ratings/): API рэйтынгаў фільмаў вяртае ацэнкі IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB для назвы адным выклікам, з null для крыніцы, якая невядомая.
- [Пошук па вонкавым ідэнтыфікатары](https://amodb.dev/be/find-by-external-id/): Шукайце фільм, серыял або персону па IMDb, TVDB, Wikidata ці Kinopoisk id праз эндпоінт find TMDB і чытайце вонкавыя id і факты Wikidata для назвы.
- [Мовы](https://amodb.dev/be/languages/): amodb аддае назвы, апісанні і імёны на 14 мовах. Перадайце тэг у стылі TMDB, напрыклад ru-RU або pt-BR, у language; любы іншы тэг замяняецца англійскай мовай.
- [Альтэрнатыва IMDb API](https://amodb.dev/be/imdb-api-alternative/): У IMDb няма бясплатнага REST API. Шукайце назвы па IMDb id, чытайце рэйтынг IMDb, калі ён вядомы, і бярыце акцёраў, выявы і трэйлеры з платнага JSON API.
- [Цэны](https://amodb.dev/be/pricing/): Планы amodb адрозніваюцца толькі лікам запытаў у хвіліну: 20, 40 або 120. Усе даныя TMDB v3 і OMDb у кожным плане. Аплата наперад, без аўтапрадаўжэння.

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