Hodnocení filmů a seriálů

GET /3/movie/{movie_id}/ratings a GET /3/tv/{tv_id}/ratings vracejí skóre z IMDb, Kinopoisk, Metacritic, Rotten Tomatoes a TMDB. Každý zdroj je objekt s value a votes, nebo null, když je neznámý. IMDb, Kinopoisk a TMDB jsou z 10, zbylé dva ze 100. Přidejte append_to_response=ratings a sloučíte je do detailů.

Aktualizováno Zobrazit jako Markdown

Získání hodnocení filmu

GET /3/movie/{movie_id}/ratings vrací skóre, která zdroje hodnocení zveřejňují pro jeden film. Odpověď má id filmu a pět klíčů zdrojů: imdb, kinopoisk, metacritic, rotten_tomatoes a tmdb. Každý klíč zdroje obsahuje objekt s value a votes, nebo null, když tento zdroj titul nezná.

Ukázka načte Fight Club (ID 550) a vypíše každý zdroj, neznámé označí.

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

Parametry

  • movie_idpathpovinný
    Číselné ID filmu, například 550.
  • api_keyqueryjeden ze dvou
    Váš klíč. Použijte jej, nebo hlavičku Authorization: Bearer.

Pole odpovědi

PoleTypPoznámky
idintegerID filmu. Při použití append_to_response chybí.
imdbobject nebo nullSkóre IMDb, z 10 na jedno desetinné místo.
kinopoiskobject nebo nullSkóre Kinopoisk, z 10 na jedno desetinné místo.
metacriticobject nebo nullSkóre Metacritic, ze 100 jako celé číslo.
rotten_tomatoesobject nebo nullSkóre Rotten Tomatoes, ze 100 jako celé číslo.
tmdbobject nebo nullSkóre uživatelů TMDB, z 10 až na tři desetinná místa.
valuenumberUvnitř každého objektu zdroje. Skóre na vlastní stupnici daného zdroje.
votesinteger nebo nullUvnitř každého objektu zdroje. Počet hlasů za skórem, nebo null, když není znám.

Pět klíčů zdrojů čtěte podle názvu a ostatní klíče přeskočte. Klíče zdrojů vždy přicházejí ve stejném pořadí: imdb, kinopoisk, metacritic, rotten_tomatoes, tmdb.

Příklad odpovědi

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

Počet hlasů zde mají jen IMDb a TMDB. Kinopoisk, Metacritic a Rotten Tomatoes mají skóre a počet hlasů null.

Získání hodnocení seriálu

GET /3/tv/{tv_id}/ratings má stejné klíče a stejná pravidla pro null. Předejte ID seriálu, například 1396 pro Breaking Bad.

Metoda a cestaVracíParametry
GET /3/movie/{movie_id}/ratingsid a pět zdrojůmovie_id
GET /3/tv/{tv_id}/ratingsid a pět zdrojůtv_id
curl
curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY"

Breaking Bad nemá skóre Metacritic, takže tento zdroj je 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 }
}

Přidání hodnocení k volání detailů

append_to_response=ratings funguje u detailů filmů i seriálů. Objekt přijde pod klíčem ratings vedle obvyklých polí, bez vlastního id. Stránka se seznamem potřebuje jeden požadavek na titul místo dvou.

PožadavekKde se skóre objeví
/3/movie/550?append_to_response=ratingsratings v záznamu filmu
/3/tv/1396?append_to_response=credits,ratingsratings a credits v záznamu seriálu

Další hodnoty, které lze přidat, viz detail filmu a seriály.

Zdroje a hodnoty null

Zdroj null není nulové skóre. Znamená, že skóre pro titul chybí.

KlíčZdrojStupnicePopisek k zobrazení
imdbIMDb0 až 10IMDb
kinopoiskKinopoisk0 až 10Kinopoisk
metacriticMetacritic0 až 100Metacritic
rotten_tomatoesRotten Tomatoes0 až 100Rotten Tomatoes
tmdbTMDB0 až 10TMDB

Pokrytí se liší podle titulu, programujte proto proti null, ne proti pevnému seznamu zdrojů. Kterýkoli z pěti klíčů může být u kteréhokoli titulu null.

Čím se hodnocení liší od vote_average

Pole vote_average a vote_count v záznamu filmu nebo seriálu jsou skóre uživatelů TMDB. Klíč tmdb nese stejné skóre ve stejném tvaru jako ostatní čtyři, takže jedno volání dá všech pět zdrojů v jednom formátu.

Každý zdroj má vlastní publikum a stupnici. Neprůměrujte je a neporovnávejte hodnotu jednoho zdroje s počtem hlasů jiného.

Zobrazení hodnocení v aplikaci

Vykreslete jen zdroje, které jsou přítomné. Pro kartu stačí krátký seznam odznaků. Přidejte stupnici, aby čtenář rozeznal 8.8 z 10 od 67 ze 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}`);
}

U každé hodnoty zobrazte popisek. Když je všech pět null, blok skryjte místo zobrazení prázdných odznaků.

Chyby

Selhání zachovávají tělo chyby TMDB, kde success je false a status_code pojmenuje problém. Titul bez skóre mezi ně nepatří.

HTTPstatus_codeKdy
4017Klíč chybí nebo je nesprávný.
40236Platnost tarifu skončila.
40434Film ani seriál s tímto ID neexistuje.
42925Překročen počet požadavků za minutu. Počkejte tolik sekund, kolik říká Retry-After.

Neznámé skóre je null, ne chyba. Podrobnosti jsou na stránkách chyby a limity požadavků.

Praktické poznámky

  • Hodnocení se na edge cachují 6 hodin, stejně jako detaily. Častější obnova vrací stejné tělo.
  • Požadavek s append_to_response=ratings se počítá jako jeden požadavek z vašich 20, 40 nebo 120 požadavků za minutu.
  • Ukládejte skóre s datem, kdy jste je stáhli. Hlasů přibývá a čísla se hýbou.
  • Chcete-li ID z IMDb nebo Kinopoisku nejdřív převést na titul, použijte hledání podle externího ID. Pro pocity místo skóre viz nálady.