Alternative à l'API Kinopoisk

Ce qu'une alternative peut et ne peut pas vous apporter

Kinopoisk est un site de cinéma en langue russe et il ne publie pas d'API ouverte généraliste. Les développeurs se tournent souvent vers des services tiers, chacun avec ses propres conditions, consultez donc leur documentation. amodb est une API indépendante et non un service Kinopoisk. Elle répond à trois besoins fréquents des projets en russe : titres et résumés en russe, recherche par identifiant Kinopoisk, et note Kinopoisk à côté des autres notes quand elle est connue.

Les briques de base

Le bloc suivant montre une réponse de détails en russe avec append_to_response=ratings. C'est une vraie réponse pour Fight Club (id 550), réduite aux champs utilisés ici, avec un résumé raccourci.

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

L'objet ratings liste toujours les mêmes cinq clés. Ici, la note Kinopoisk est de 8,7 et son votes vaut null : on ne peut donc pas tenir pour acquis un nombre de votes Kinopoisk. Les détails sont sur la page notes.

Comparatif des fonctionnalités

Ce qui distingue amodb

• Un contrat documenté. Les chemins, les paramètres, les corps d'erreur et les limites sont écrits noir sur blanc, et une seule clé sert tous les points de terminaison.
• Le russe à côté d'autres langues. Le même appel avec une autre valeur de language renvoie les mêmes champs dans une autre langue. C'est utile quand votre public lit le russe, l'ukrainien et l'anglais.
• Plusieurs notes dans un seul objet. Vous pouvez afficher la note Kinopoisk à côté d'IMDb, de Metacritic et de Rotten Tomatoes, chacune valant null quand elle est inconnue.
• Titres originaux conservés. original_title et original_name contiennent le titre dans sa langue d'origine, y compris le japonais et le coréen, même s'il ne s'agit pas de langues d'interface.

Quand Kinopoisk convient mieux

• La communauté elle-même. Les critiques, les listes, les pages d'utilisateurs et les discussions locales vivent sur le site. amodb n'offre rien de tout cela, seulement la note quand elle est connue.
• Tout ce qui dépasse les métadonnées. Pour un contenu qui n'est pas un champ de métadonnées, utilisez le site lui-même. Une API de métadonnées ne le transporte pas.
• Sa propre note du public. La valeur y est produite en premier. Dans amodb, elle peut valoir null pour un titre récent ou peu connu, et le nombre de votes peut valoir null même quand la note est renseignée.

Migrer vers amodb

Rassemblez les identifiants Kinopoisk que vous stockez, associez-les une fois avec /3/find et conservez l'identifiant numérique amodb à côté. Ensuite, demandez les détails en russe et lisez la note dans la même réponse.

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

Un tableau movie_results vide signifie qu'aucun titre ne correspond à cet identifiant. L'identifiant Kinopoisk d'une série remplit tv_results à la place : lisez donc les deux tableaux quand vous ne connaissez pas le type. Pour une réponse 429, attendez le nombre de secondes indiqué par Retry-After. La liste des langues est sur langues, et les règles de recherche sont sur recherche par identifiant externe.

Gérer les manques dans le texte russe

Un champ de texte peut être vide quand il n'existe pas de traduction russe pour un titre. Testez la chaîne vide et redemandez ce titre avec language=en-US. Pour les affiches avec du texte en russe, appelez /3/movie/550/images?include_image_language=ru,null et choisissez dans posters. La valeur null garde dans la liste les visuels sans texte. Voir images pour les tailles.

Tarifs

amodb n'a pas d'offre gratuite. Vous payez d'avance 1, 3, 6, 12 ou 24 mois sur l'une des trois offres, et une période plus longue coûte 10, 20, 30 ou 40 pour cent de moins. Les offres autorisent 20, 40 ou 120 requêtes par minute, renvoient les mêmes données et ne se renouvellent pas automatiquement. Les montants sont sur les tarifs.