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

Kinopoisk це російськомовний сайт про кіно, і він не публікує загального відкритого API. Натомість розробники часто користуються сторонніми сервісами, кожен зі своїми умовами, тож перевіряйте їхню документацію. amodb це незалежний API, а не сервіс Kinopoisk. Він закриває три потреби, які часто мають російськомовні проєкти: назви й описи російською, пошук за id Kinopoisk та оцінка Kinopoisk поруч з іншими оцінками, де вона відома.

Будівельні блоки

Вам потрібноЯкЩо повертається
Російська назва й описlanguage=ru-RU у будь-якому виклику деталейtitle російською, original_title без змін
Тайтл за id KinopoiskGET /3/find/361?external_source=kinopoisk_idmovie_results з id 550
Id Kinopoisk тайтлаGET /3/movie/550/external_idskinopoisk_id як рядок, тут "361"
Оцінка KinopoiskGET /3/movie/550/ratingskinopoisk з 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 не можна вважати гарантованою. Подробиці на сторінці рейтинги.

Порівняння можливостей

МожливістьKinopoiskamodb
Модель оплатиНемає загального відкритого API, про сторонні сервіси дивіться їхню документаціюПередплата, від 1 до 24 місяців за покупку
Безкоштовний тарифДивіться їхню документаціюНемає, пробного періоду теж
АвтентифікаціяДивіться їхню документаціюapi_key або заголовок Bearer
Формат відповідіДивіться їхню документаціюJSON у структурі TMDB v3
МовиРосійськомовний сайт14 мов інтерфейсу, серед них російська
ФільмиНа вебсайтіДеталі, акторський склад, зображення, відео
СеріалиНа вебсайтіСеріали, сезони та серії
ПерсониНа вебсайтіПрофілі та фільмографія
ЗображенняНа вебсайтіimg.amodb.dev, ключ не потрібен
РейтингиВласна оцінка глядачів на вебсайтіОцінка Kinopoisk плюс чотири інші джерела, де відомо
Ліміт запитівДивіться їхню документацію20, 40 або 120 на хвилину на ключ
Комерційне використанняДивіться їхню документаціюПлатні тарифи, дивіться ціни
СумісністьНемає загального відкритого API, дивіться їхню документаціюЧитання TMDB v3 та OMDb

Чим відрізняється 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 поруч. Після цього запитуйте деталі російською і читайте оцінку з тієї самої відповіді.

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 збігів немає. 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 запитів на хвилину, повертають ті самі дані й не поновлюються автоматично. Суми на сторінці ціни.