Avaliações de filmes e séries

GET /3/movie/{movie_id}/ratings e GET /3/tv/{tv_id}/ratings retornam as notas do IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB. Cada fonte é um objeto com value e votes, ou null quando desconhecida. IMDb, Kinopoisk e TMDB vão até 10, as outras duas até 100. Adicione append_to_response=ratings para juntar tudo aos detalhes.

Atualizado em Ver em Markdown

Obter as avaliações de um filme

GET /3/movie/{movie_id}/ratings retorna as notas que as fontes de avaliação publicam para um filme. A resposta tem o id do filme e cinco chaves de fonte: imdb, kinopoisk, metacritic, rotten_tomatoes e tmdb. Cada chave de fonte contém um objeto com value e votes, ou null quando essa fonte não é conhecida para o título.

O exemplo carrega Fight Club (id 550) e exibe todas as fontes, marcando as desconhecidas.

bashjspyphpgo
curl -sf "https://api.amodb.dev/3/movie/550/ratings" \
  -H "Authorization: Bearer $AMODB_KEY"
const res = await fetch('https://api.amodb.dev/3/movie/550/ratings', {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const ratings = await res.json();
for (const source of ['imdb', 'kinopoisk', 'metacritic', 'rotten_tomatoes', 'tmdb']) {
  const score = ratings[source];
  console.log(source, score ? `${score.value} (votes: ${score.votes ?? 'unknown'})` : 'not known');
}
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/550/ratings",
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
ratings = r.json()
for source in ("imdb", "kinopoisk", "metacritic", "rotten_tomatoes", "tmdb"):
    score = ratings[source]
    if score is None:
        print(source, "not known")
    else:
        print(source, score["value"], "votes:", score["votes"] or "unknown")
<?php
$ch = curl_init('https://api.amodb.dev/3/movie/550/ratings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$ratings = json_decode($body, true);
foreach (['imdb', 'kinopoisk', 'metacritic', 'rotten_tomatoes', 'tmdb'] as $source) {
    $score = $ratings[$source];
    echo $source, ' ', $score === null ? 'not known' : $score['value'] . ' votes: ' . ($score['votes'] ?? 'unknown'), PHP_EOL;
}
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Score struct {
	Value float64 `json:"value"`
	Votes *int    `json:"votes"`
}

type Ratings struct {
	IMDb           *Score `json:"imdb"`
	Kinopoisk      *Score `json:"kinopoisk"`
	Metacritic     *Score `json:"metacritic"`
	RottenTomatoes *Score `json:"rotten_tomatoes"`
	TMDB           *Score `json:"tmdb"`
}

func show(name string, s *Score) {
	if s == nil {
		fmt.Println(name, "not known")
		return
	}
	if s.Votes == nil {
		fmt.Println(name, s.Value, "votes: unknown")
		return
	}
	fmt.Println(name, s.Value, "votes:", *s.Votes)
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/ratings", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var r Ratings
	if err := json.NewDecoder(res.Body).Decode(&r); err != nil {
		panic(err)
	}
	show("imdb", r.IMDb)
	show("kinopoisk", r.Kinopoisk)
	show("metacritic", r.Metacritic)
	show("rotten_tomatoes", r.RottenTomatoes)
	show("tmdb", r.TMDB)
}

Parâmetros

  • movie_idcaminhoobrigatório
    Id numérico do filme, por exemplo 550.
  • api_keyconsultaum dos dois
    Sua chave. Use este parâmetro ou o header Authorization: Bearer.

Campos da resposta

CampoTipoObservações
idinteiroId do filme. Ausente quando você usa append_to_response.
imdbobjeto ou nullNota do IMDb, em escala de 10 com uma casa decimal.
kinopoiskobjeto ou nullNota do Kinopoisk, em escala de 10 com uma casa decimal.
metacriticobjeto ou nullNota do Metacritic, em escala de 100 como inteiro.
rotten_tomatoesobjeto ou nullNota do Rotten Tomatoes, em escala de 100 como inteiro.
tmdbobjeto ou nullNota dos usuários do TMDB, em escala de 10 com até três casas decimais.
valuenúmeroDentro de cada objeto de fonte. A nota na escala própria dessa fonte.
votesinteiro ou nullDentro de cada objeto de fonte. Número de votos por trás da nota, ou null quando não é conhecido.

Leia as cinco chaves de fonte pelo nome e ignore qualquer outra chave. As chaves de fonte vêm sempre na mesma ordem: imdb, kinopoisk, metacritic, rotten_tomatoes, tmdb.

Exemplo de resposta

JSON
{
  "id": 550,
  "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 }
}

Aqui só IMDb e TMDB vêm com contagem de votos. Kinopoisk, Metacritic e Rotten Tomatoes têm uma nota e uma contagem de votos null.

Obter as avaliações de uma série

GET /3/tv/{tv_id}/ratings tem as mesmas chaves e as mesmas regras de null. Passe o id da série, por exemplo 1396 para Breaking Bad.

Método e caminhoRetornaParâmetros
GET /3/movie/{movie_id}/ratingsid e cinco fontesmovie_id
GET /3/tv/{tv_id}/ratingsid e cinco fontestv_id
curl
curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY"

Breaking Bad não tem nota do Metacritic, então essa fonte é null:

JSON
{
  "id": 1396,
  "imdb": { "value": 9.5, "votes": 2671962 },
  "kinopoisk": { "value": 8.9, "votes": null },
  "metacritic": null,
  "rotten_tomatoes": { "value": 96, "votes": null },
  "tmdb": { "value": 9, "votes": 18863 }
}

Adicionar avaliações a uma chamada de detalhes

append_to_response=ratings funciona nos detalhes de filmes e de séries. O objeto chega sob a chave ratings, ao lado dos campos habituais, sem id próprio. Uma página de lista precisa de uma requisição por título em vez de duas.

RequisiçãoOnde as notas aparecem
/3/movie/550?append_to_response=ratingsratings no registro do filme
/3/tv/1396?append_to_response=credits,ratingsratings e credits no registro da série

Veja os detalhes de filmes e as séries de TV para os outros valores que você pode acrescentar.

Fontes e valores null

Uma fonte null não é uma nota zero. Significa que a nota não existe para o título.

ChaveFonteEscalaRótulo a exibir
imdbIMDb0 a 10IMDb
kinopoiskKinopoisk0 a 10Kinopoisk
metacriticMetacritic0 a 100Metacritic
rotten_tomatoesRotten Tomatoes0 a 100Rotten Tomatoes
tmdbTMDB0 a 10TMDB

A cobertura varia por título, então programe para o null, e não para uma lista fixa de fontes. Qualquer uma das cinco chaves pode ser null em qualquer título.

Diferença entre avaliações e vote_average

Os campos vote_average e vote_count de um registro de filme ou série são a nota dos usuários do TMDB. A chave tmdb traz a mesma nota no mesmo formato das outras quatro, então uma chamada dá as cinco fontes em um só formato.

Cada fonte tem seu próprio público e sua própria escala. Não calcule a média entre elas nem compare um valor de uma fonte com a contagem de votos de outra.

Exibir avaliações em um app

Exiba só as fontes presentes. Uma lista curta de selos basta para um card. Acrescente a escala para que o leitor saiba distinguir 8.8 em 10 de 67 em 100.

JavaScript
const labels = {
  imdb: ['IMDb', 10],
  kinopoisk: ['Kinopoisk', 10],
  metacritic: ['Metacritic', 100],
  rotten_tomatoes: ['Rotten Tomatoes', 100],
  tmdb: ['TMDB', 10],
};

function badges(ratings) {
  return Object.entries(labels)
    .filter(([key]) => ratings[key])
    .map(([key, [label, max]]) => `${label} ${ratings[key].value}/${max}`);
}

Mostre o rótulo com cada valor. Quando as cinco forem null, oculte o bloco em vez de mostrar selos vazios.

Erros

As falhas mantêm o corpo de erro do TMDB, em que success é false e status_code indica o problema. Um título sem notas não é uma delas.

HTTPstatus_codeQuando
4017A chave está ausente ou incorreta.
40236O período do plano terminou.
40434Nenhum filme ou série com esse id.
42925Acima do seu limite de requisições por minuto. Espere os segundos indicados em Retry-After.

Uma nota desconhecida é null, não um erro. Os detalhes estão em erros e limites de requisições.

Notas práticas

  • As avaliações ficam em cache de borda por 6 horas, como os detalhes. Atualizar com mais frequência retorna o mesmo corpo.
  • Uma requisição com append_to_response=ratings conta como uma requisição nas suas 20, 40 ou 120 requisições por minuto.
  • Guarde as notas com a data em que você as buscou. Os votos crescem com o tempo e os números mudam.
  • Para mapear antes um id do IMDb ou do Kinopoisk para um título, use buscar por ID externo. Para sensações em vez de notas, veja os moods.