Alternativa all'API Kinopoisk

Cosa può e cosa non può darti un'alternativa

Kinopoisk è un sito di cinema in lingua russa e non pubblica un'API aperta generica. Gli sviluppatori usano spesso servizi di terze parti, ciascuno con le proprie condizioni, quindi controlla la loro documentazione. amodb è un'API indipendente e non un servizio Kinopoisk. Copre tre esigenze frequenti nei progetti in lingua russa: titoli e trame in russo, ricerca per ID Kinopoisk e punteggio Kinopoisk accanto agli altri punteggi, quando è noto.

I blocchi di base

Il blocco seguente mostra una risposta di dettaglio in russo con append_to_response=ratings. È una risposta reale per Fight Club (id 550), ridotta ai campi usati qui e con la trama accorciata.

{
  "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'oggetto ratings elenca sempre le stesse cinque chiavi. Qui il punteggio Kinopoisk è 8,7 e il suo votes è null, quindi il numero di voti di Kinopoisk non si può dare per scontato. I dettagli sono nella pagina valutazioni.

Confronto delle funzionalità

Dove amodb è diverso

• Un contratto documentato. Percorsi, parametri, corpi degli errori e limiti sono scritti nero su bianco, e una sola chiave serve tutti gli endpoint.
• Il russo accanto ad altre lingue. La stessa chiamata con un altro valore di language restituisce gli stessi campi in un'altra lingua. È utile quando il tuo pubblico legge russo, ucraino e inglese.
• Più punteggi in un solo oggetto. Puoi mostrare il punteggio Kinopoisk accanto a IMDb, Metacritic e Rotten Tomatoes, ciascuno null quando è sconosciuto.
• Titoli originali conservati. original_title e original_name contengono il titolo nella lingua di origine, compresi giapponese e coreano, anche se non sono lingue dell'interfaccia.

Dove Kinopoisk è più adatto

• La community stessa. Recensioni, liste, pagine utente e discussioni locali vivono sul sito. amodb non offre nulla di tutto questo, solo il punteggio quando è noto.
• Tutto ciò che va oltre i metadati. Per i contenuti che non sono un campo di metadati usa il sito stesso. Un'API di metadati non li trasporta.
• Il suo punteggio del pubblico. Il valore nasce lì per primo. In amodb può essere null per un titolo nuovo o poco conosciuto, e il numero di voti può essere null anche quando il punteggio è impostato.

Migrare ad amodb

Raccogli gli ID Kinopoisk che conservi, associali una volta con /3/find e tieni accanto l'ID numerico di amodb. Poi richiedi i dettagli in russo e leggi il punteggio dalla stessa risposta.

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 array movie_results vuoto significa che per quell'ID non c'è corrispondenza. L'ID Kinopoisk di una serie riempie invece tv_results, quindi leggi entrambi gli array quando non conosci il tipo. Gestisci un 429 attendendo i secondi indicati da Retry-After. L'elenco delle lingue è nella pagina lingue e le regole di ricerca nella pagina ricerca per ID esterno.

Gestire le lacune nel testo russo

Un campo di testo può essere vuoto quando per un titolo non esiste una traduzione in russo. Controlla se la stringa è vuota e richiedi di nuovo quel titolo con language=en-US. Per le locandine con scritte in russo chiama /3/movie/550/images?include_image_language=ru,null e scegli da posters. Il valore null mantiene nell'elenco le immagini senza testo. Vedi immagini per le dimensioni.

Prezzi

amodb non ha un piano gratuito. Paghi in anticipo 1, 3, 6, 12 o 24 mesi su uno dei tre piani, e un periodo più lungo costa il 10, 20, 30 o 40 per cento in meno. I piani consentono 20, 40 o 120 richieste al minuto, restituiscono gli stessi dati e non si rinnovano automaticamente. Gli importi sono nella pagina prezzi.