Kinopoisk API alternative

What an alternative can and cannot give you

Kinopoisk is a Russian-language movie site, and it does not publish a general open API. Developers often use third-party services instead, each with its own terms, so check their docs. amodb is an independent API and not a Kinopoisk service. It covers three needs that Russian-language projects often have: titles and overviews in Russian, a lookup by Kinopoisk id, and the Kinopoisk score next to other scores where it is known.

Building blocks

The next block shows one detail response in Russian with append_to_response=ratings. It is a real reply for Fight Club (id 550), cut to the fields used here and with the overview shortened.

{
  "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
    }
  }
}

The ratings object always lists the same five keys. Here the Kinopoisk score is 8.7 and its votes is null, so a Kinopoisk vote count cannot be taken for granted. Details are on the ratings page.

Feature comparison

Where amodb differs

• A documented contract. Paths, parameters, error bodies and limits are written down, and one key serves every endpoint.
• Russian next to other languages. The same call with another language value gives the same fields in another language. That helps when your audience reads Russian, Ukrainian and English.
• Several scores in one object. You can show the Kinopoisk score beside IMDb, Metacritic and Rotten Tomatoes, each one null when it is unknown.
• Original titles kept. original_title and original_name hold the title in its source language, including Japanese and Korean, even though those are not interface languages.

Where Kinopoisk is a better fit

• The community itself. Reviews, lists, user pages and local discussion live on the site. amodb offers none of that, only the score where known.
• Everything beyond metadata. For content that is not a metadata field, use the site itself. A metadata API does not carry it.
• Its own audience score. The value is produced there first. In amodb it can be null for a new or little known title, and the vote count can be null even when the score is set.

Migrate to amodb

Collect the Kinopoisk ids you store, map them once with /3/find, and keep the numeric amodb id next to them. After that, request details in Russian and read the score from the same response.

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")

An empty movie_results array means no match for that id. A Kinopoisk id of a series fills tv_results instead, so read both arrays when you do not know the kind. Handle a 429 by waiting the Retry-After seconds. The language list is on languages, and the lookup rules are on find by external id.

Handle gaps in Russian text

A text field can be empty when no Russian translation exists for a title. Check for an empty string and request that one title again with language=en-US. For posters with Russian lettering, call /3/movie/550/images?include_image_language=ru,null and pick from posters. The null value keeps textless artwork in the list. See images for sizes.

Pricing

amodb has no free tier. You prepay 1, 3, 6, 12 or 24 months on one of three plans, and a longer period costs 10, 20, 30 or 40 percent less. The plans allow 20, 40 or 120 requests per minute, return the same data and do not renew automatically. Amounts are on pricing.