Alternativa à API do Kinopoisk

O que uma alternativa pode e não pode oferecer

O Kinopoisk é um site de filmes em russo e não publica uma API aberta de uso geral. Desenvolvedores costumam usar serviços de terceiros, cada um com seus próprios termos, então consulte a documentação deles. O amodb é uma API independente e não um serviço do Kinopoisk. Ele cobre três necessidades comuns em projetos em russo: títulos e sinopses em russo, a busca por ID do Kinopoisk e a nota do Kinopoisk ao lado de outras notas, quando conhecida.

Blocos de construção

O próximo bloco mostra uma resposta de detalhes em russo com append_to_response=ratings. É uma resposta real para Fight Club (ID 550), reduzida aos campos usados aqui e com a sinopse encurtada.

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

O objeto de avaliações sempre lista as mesmas cinco chaves. Aqui a nota do Kinopoisk é 8.7 e o votes é null, então não dá para presumir que exista um número de votos do Kinopoisk. Os detalhes estão na página de avaliações.

Comparação de recursos

Onde o amodb se diferencia

• Um contrato documentado. Caminhos, parâmetros, corpos de erro e limites estão escritos, e uma chave atende todos os endpoints.
• Russo ao lado de outros idiomas. A mesma chamada com outro valor de language devolve os mesmos campos em outro idioma. Isso ajuda quando o seu público lê russo, ucraniano e inglês.
• Várias notas em um objeto. Você pode mostrar a nota do Kinopoisk ao lado de IMDb, Metacritic e Rotten Tomatoes, cada uma null quando é desconhecida.
• Títulos originais preservados. original_title e original_name guardam o título no idioma de origem, inclusive japonês e coreano, mesmo que esses não sejam idiomas de interface.

Onde o Kinopoisk é mais indicado

• A própria comunidade. Resenhas, listas, páginas de usuários e discussões locais ficam no site. O amodb não oferece nada disso, só a nota quando conhecida.
• Tudo além dos metadados. Para conteúdo que não é um campo de metadados, use o próprio site. Uma API de metadados não o carrega.
• A nota própria do público. O valor é produzido lá primeiro. No amodb ele pode ser null para um título novo ou pouco conhecido, e o número de votos pode ser null mesmo com a nota preenchida.

Migrar para o amodb

Reúna os IDs do Kinopoisk que você guarda, mapeie-os uma vez com /3/find e mantenha o ID numérico do amodb ao lado. Depois disso, peça os detalhes em russo e leia a nota na mesma resposta.

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

Um array movie_results vazio significa que não há correspondência para aquele ID. O ID do Kinopoisk de uma série preenche tv_results, então leia os dois arrays quando não souber o tipo. Trate um 429 esperando os segundos de Retry-After. A lista de idiomas está em idiomas, e as regras de busca estão em busca por ID externo.

Lidar com lacunas no texto em russo

Um campo de texto pode vir vazio quando não existe tradução em russo para um título. Verifique se há uma string vazia e peça esse título de novo com language=en-US. Para pôsteres com letras em russo, chame /3/movie/550/images?include_image_language=ru,null e escolha em posters. O valor null mantém as artes sem texto na lista. Veja imagens para os tamanhos.

Preços

O amodb não tem plano gratuito. Você pré-paga 1, 3, 6, 12 ou 24 meses em um de três planos, e um período maior custa 10, 20, 30 ou 40 por cento menos. Os planos permitem 20, 40 ou 120 requisições por minuto, retornam os mesmos dados e não renovam automaticamente. Os valores estão em preços.