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

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

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

Збярыце Kinopoisk id, якія вы захоўваеце, адзін раз супастаўце іх праз /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 няма супадзення. Kinopoisk id серыяла запаўняе замест гэтага tv_results, таму чытайце абодва масівы, калі не ведаеце тып. Пры 429 пачакайце Retry-After секунд. Спіс моў ёсць на старонцы мовы, а правілы пошуку на старонцы пошук па вонкавым ідэнтыфікатары.

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

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

Цэны

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