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.
Obter as avaliações de um filme
GET / 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.
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órioId numérico do filme, por exemplo550.api_keyconsultaum dos doisSua chave. Use este parâmetro ou o headerAuthorization: Bearer.
Campos da resposta
| Campo | Tipo | Observações |
|---|---|---|
id | inteiro | Id do filme. Ausente quando você usa append_to_response. |
imdb | objeto ou null | Nota do IMDb, em escala de 10 com uma casa decimal. |
kinopoisk | objeto ou null | Nota do Kinopoisk, em escala de 10 com uma casa decimal. |
metacritic | objeto ou null | Nota do Metacritic, em escala de 100 como inteiro. |
rotten_tomatoes | objeto ou null | Nota do Rotten Tomatoes, em escala de 100 como inteiro. |
tmdb | objeto ou null | Nota dos usuários do TMDB, em escala de 10 com até três casas decimais. |
value | número | Dentro de cada objeto de fonte. A nota na escala própria dessa fonte. |
votes | inteiro ou null | Dentro 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
{
"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 / 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 caminho | Retorna | Parâmetros |
|---|---|---|
GET / | id e cinco fontes | movie_id |
GET / | id e cinco fontes | tv_id |
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:
{
"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_ 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ção | Onde as notas aparecem |
|---|---|
/ | ratings no registro do filme |
/ | ratings 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.
| Chave | Fonte | Escala | Rótulo a exibir |
|---|---|---|---|
imdb | IMDb | 0 a 10 | IMDb |
kinopoisk | Kinopoisk | 0 a 10 | Kinopoisk |
metacritic | Metacritic | 0 a 100 | Metacritic |
rotten_tomatoes | Rotten Tomatoes | 0 a 100 | Rotten Tomatoes |
tmdb | TMDB | 0 a 10 | TMDB |
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.
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.
| HTTP | status_code | Quando |
|---|---|---|
| 401 | 7 | A chave está ausente ou incorreta. |
| 402 | 36 | O período do plano terminou. |
| 404 | 34 | Nenhum filme ou série com esse id. |
| 429 | 25 | Acima 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_conta como uma requisição nas suas 20, 40 ou 120 requisições por minuto.to_ response= ratings - 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.