Valutazioni di film e serie TV

Ottenere le valutazioni di un film

GET /3/movie/{movie_id}/ratings restituisce i punteggi che le fonti di valutazione pubblicano per un film. La risposta ha l'id del film e cinque chiavi di fonti: imdb, kinopoisk, metacritic, rotten_tomatoes e tmdb. Ogni chiave di fonte contiene un oggetto con value e votes, oppure null quando quella fonte non è nota per il titolo.

L'esempio carica Fight Club (id 550) e stampa ogni fonte, segnando quelle sconosciute.

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

Parametri

• movie_idpercorsoobbligatorio
  ID numerico del film, per esempio 550.
• api_keyqueryuno dei due
  La tua chiave. Usa questa o l'header Authorization: Bearer.

Campi della risposta

Leggi le cinque chiavi di fonte per nome e salta qualsiasi altra chiave. Le chiavi di fonte arrivano sempre nello stesso ordine: imdb, kinopoisk, metacritic, rotten_tomatoes, tmdb.

Risposta di esempio

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

Qui solo IMDb e TMDB hanno un numero di voti. Kinopoisk, Metacritic e Rotten Tomatoes hanno un punteggio e un numero di voti null.

Ottenere le valutazioni di una serie TV

GET /3/tv/{tv_id}/ratings ha le stesse chiavi e le stesse regole sul null. Passa l'ID della serie, per esempio 1396 per Breaking Bad.

curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY"

Breaking Bad non ha un punteggio Metacritic, quindi quella 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 }
}

Aggiungere le valutazioni a una chiamata di dettagli

append_to_response=ratings funziona sui dettagli di film e serie TV. L'oggetto arriva sotto la chiave ratings accanto ai campi consueti, senza un id proprio. Una pagina di lista richiede una richiesta per titolo invece di due.

Vedi dettagli del film e serie TV per gli altri valori che puoi aggiungere.

Fonti e valori null

Una fonte null non è un punteggio pari a zero. Significa che il punteggio manca per il titolo.

La copertura varia da titolo a titolo, quindi scrivi il codice per gestire il null, non per un elenco fisso di fonti. Una qualsiasi delle cinque chiavi può essere null per qualsiasi titolo.

In cosa le valutazioni differiscono da vote_average

I campi vote_average e vote_count di una scheda di film o serie sono il punteggio degli utenti TMDB. La chiave tmdb porta lo stesso punteggio nella stessa forma delle altre quattro, quindi una sola chiamata dà tutte e cinque le fonti in un unico formato.

Ogni fonte ha un proprio pubblico e una propria scala. Non farne la media e non confrontare un valore di una fonte con il numero di voti di un'altra.

Mostrare le valutazioni in un'app

Mostra solo le fonti presenti. Un breve elenco di badge basta per una scheda. Aggiungi la scala così chi legge distingue 8.8 su 10 da 67 su 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}`);
}

Mostra l'etichetta con ogni valore. Quando tutte e cinque sono null, nascondi il blocco invece di mostrare badge vuoti.

Errori

Gli errori mantengono il corpo di errore TMDB, dove success è false e status_code indica il problema. Un titolo senza punteggi non è tra questi.

Un punteggio sconosciuto è null, non un errore. I dettagli sono nelle pagine errori e limiti di richieste.

Note pratiche

• Le valutazioni restano in cache sull'edge per 6 ore, come i dettagli. Aggiornarle più spesso restituisce lo stesso corpo.
• Una richiesta con append_to_response=ratings conta come una sola richiesta nelle tue 20, 40 o 120 richieste al minuto.
• Salva i punteggi con la data in cui li hai recuperati. I voti crescono nel tempo e i numeri si muovono.
• Per associare prima un ID IMDb o Kinopoisk a un titolo, usa la ricerca per ID esterno. Per le sensazioni invece dei punteggi, vedi mood.