Альтернатива Kinopoisk API

Что может и чего не может дать альтернатива

Kinopoisk является русскоязычным сайтом о кино и не публикует общий открытый API. Вместо него разработчики часто используют сторонние сервисы, у каждого из которых свои условия, поэтому уточняйте их документацию. amodb является независимым API, а не сервисом Kinopoisk. Он закрывает три потребности, которые часто возникают у русскоязычных проектов: названия и описания на русском, поиск по ID Kinopoisk и оценка Kinopoisk рядом с другими оценками, где она известна.

Составные части

В следующем блоке показан один ответ с деталями на русском с append_to_response=ratings. Это реальный ответ для Fight Club (ID 550), сокращенный до используемых здесь полей, с укороченным описанием.

{
  "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 нельзя считать гарантированным. Подробности приведены на странице рейтинги.

Сравнение возможностей

Чем отличается amodb

• Документированный контракт. Пути, параметры, тела ошибок и лимиты описаны, а один ключ обслуживает все эндпоинты.
• Русский рядом с другими языками. Тот же запрос с другим значением language дает те же поля на другом языке. Это удобно, когда ваша аудитория читает по-русски, по-украински и по-английски.
• Несколько оценок в одном объекте. Оценку Kinopoisk можно показать рядом с IMDb, Metacritic и Rotten Tomatoes, и каждая из них равна null, когда неизвестна.
• Оригинальные названия сохраняются. original_title и original_name хранят название на исходном языке, включая японский и корейский, хотя они не входят в языки интерфейса.

Когда Kinopoisk подходит лучше

• Само сообщество. Отзывы, списки, страницы пользователей и обсуждения живут на сайте. amodb ничего из этого не предлагает, только оценку там, где она известна.
• Все, что выходит за рамки метаданных. Для контента, который не является полем метаданных, пользуйтесь самим сайтом. API метаданных его не содержит.
• Собственная оценка зрителей. Значение рождается именно там. В amodb оно может быть null для нового или малоизвестного тайтла, а число голосов может быть null, даже когда оценка задана.

Миграция на amodb

Соберите хранимые ID Kinopoisk, один раз сопоставьте их через /3/find и держите рядом числовой ID amodb. После этого запрашивайте детали на русском и читайте оценку из того же ответа.

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 совпадений нет. ID сериала Kinopoisk заполняет tv_results, поэтому, если вид тайтла неизвестен, читайте оба массива. Ответ 429 обрабатывайте ожиданием Retry-After секунд. Список языков приведен на странице языки, а правила поиска на странице поиск по внешнему ID.

Пробелы в русском тексте

Текстовое поле может быть пустым, если для тайтла нет русского перевода. Проверьте пустую строку и повторно запросите этот тайтл с language=en-US. Для постеров с русской надписью вызовите /3/movie/550/images?include_image_language=ru,null и выбирайте из posters. Значение null оставляет в списке изображения без текста. Размеры описаны на странице API изображений.

Цены

У amodb нет бесплатного тарифа. Вы оплачиваете вперед 1, 3, 6, 12 или 24 месяца на одном из трех тарифов, а более длинный период стоит на 10, 20, 30 или 40 процентов дешевле. Тарифы допускают 20, 40 или 120 запросов в минуту, возвращают одни и те же данные и не продлеваются автоматически. Суммы указаны на странице цены.