# 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.

## Endpoint

`GET /3/movie/{movie_id}/ratings`

```bash
curl "https://api.amodb.dev/3/movie/550/ratings" \
  -H "Authorization: Bearer $AMODB_KEY"
```

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": 33042
  }
}
```

## 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.

```bash
curl -sf "https://api.amodb.dev/3/movie/550/ratings" \
  -H "Authorization: Bearer $AMODB_KEY"
```

```js
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');
}
```

```python
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
<?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;
}
```

```go
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

| Parâmetro  | Em       | Obrigatório | Descrição                                                          |
| ---------- | -------- | ----------- | ------------------------------------------------------------------ |
| `movie_id` | caminho  | sim         | Id numérico do filme, por exemplo `550`.                           |
| `api_key`  | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: 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

```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 caminho                  | Retorna             | Parâmetros |
| --------------------------------- | ------------------- | ---------- |
| `GET /3/movie/{movie_id}/ratings` | `id` e cinco fontes | `movie_id` |
| `GET /3/tv/{tv_id}/ratings`       | `id` e cinco fontes | `tv_id`    |

```bash
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ção                                      | Onde as notas aparecem                     |
| ----------------------------------------------- | ------------------------------------------ |
| `/3/movie/550?append_to_response=ratings`       | `ratings` no registro do filme             |
| `/3/tv/1396?append_to_response=credits,ratings` | `ratings` e `credits` no registro da série |

Veja os [detalhes de filmes](https://amodb.dev/pt/movies/) e as [séries de TV](https://amodb.dev/pt/tv-series/) 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.

```js
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](https://amodb.dev/pt/errors/) e [limites de requisições](https://amodb.dev/pt/rate-limits/).

## 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](https://amodb.dev/pt/find-by-external-id/). Para sensações em vez de notas, veja os [moods](https://amodb.dev/pt/moods/).

## Perguntas e respostas

### Por que uma fonte vem null?

Null significa que a nota está ausente ou é zero para aquele título. Um lançamento recente ou um filme regional costuma ter menos fontes que um filme famoso, então trate null antes de formatar um número. O campo votes também pode ser null.

### Qual é a diferença para vote_average?

O campo vote_average de um registro de detalhes é só a nota dos usuários do TMDB. O endpoint de avaliações a retorna de novo na chave tmdb, com três casas decimais, e acrescenta as outras quatro fontes, cada uma com value e votes.

### Posso fazer a média das cinco notas?

Não faça isso. IMDb, Kinopoisk e TMDB vão até 10, enquanto Metacritic e Rotten Tomatoes vão até 100. Cada fonte também tem seu próprio público, e algumas são null. Mostre as fontes que você tem lado a lado, com seus rótulos.

### A chamada de avaliações custa requisições extras?

É uma requisição como qualquer outra. Com append_to_response=ratings as notas chegam dentro de uma chamada de detalhes, então você gasta uma requisição do seu limite por minuto em vez de duas.

## Páginas relacionadas

- [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas.
- [API de séries de TV](https://amodb.dev/pt/tv-series/): API de séries de TV com os mesmos caminhos e JSON do TMDB v3. Busque uma série por id com temporadas, emissoras, próximo episódio e classificações.
- [Buscar por ID externo](https://amodb.dev/pt/find-by-external-id/): Busque um filme, série ou pessoa por id do IMDb, TVDB, Wikidata ou Kinopoisk com o endpoint find do TMDB e leia ids externos e dados do Wikidata de um título.
- [Medidores de mood](https://amodb.dev/pt/moods/): API de moods de filmes com medidores de 0 a 10 por título. Leia os moods de um filme ou série, junte-os com append_to_response=moods e crie selos ou filtros.
- [Limites de requisições](https://amodb.dev/pt/rate-limits/): O amodb limita cada chave por requisições por minuto em uma janela de 60 segundos: 20, 40 ou 120 por plano. Leia os cabeçalhos e trate o 429 com Retry-After.
- [Início rápido](https://amodb.dev/pt/quickstart/): Faça sua primeira chamada ao amodb: obtenha uma chave, peça um filme em curl, JavaScript, Python, PHP ou Go e carregue o pôster. Menos de 2 minutos.

Atualizado: 2026-10-18. Source: https://amodb.dev/pt/ratings/