Evaluări pentru filme și TV

GET /3/movie/{movie_id}/ratings și GET /3/tv/{tv_id}/ratings întorc scorurile IMDb, Kinopoisk, Metacritic, Rotten Tomatoes și TMDB. Fiecare sursă este un obiect cu value și votes, sau null când este necunoscută. IMDb, Kinopoisk și TMDB sunt din 10, celelalte două din 100. Adaugă append_to_response=ratings ca să le îmbini în detalii.

Actualizat Vezi ca Markdown

Obține evaluările unui film

GET /3/movie/{movie_id}/ratings întoarce scorurile pe care le publică sursele de evaluări pentru un film. Răspunsul are id-ul filmului și cinci chei de sursă: imdb, kinopoisk, metacritic, rotten_tomatoes și tmdb. Fiecare cheie de sursă conține un obiect cu value și votes, sau null când acea sursă nu este cunoscută pentru titlu.

Exemplul încarcă Fight Club (ID 550) și afișează fiecare sursă, marcând sursele necunoscute.

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

Parametri

  • movie_idcaleobligatoriu
    ID numeric de film, de exemplu 550.
  • api_keyinterogareuna dintre cele două
    Cheia ta. Folosește-o pe aceasta sau antetul Authorization: Bearer.

Câmpurile răspunsului

CâmpTipObservații
idnumăr întregID-ul filmului. Lipsește când folosești append_to_response.
imdbobiect sau nullScorul IMDb, din 10, cu o zecimală.
kinopoiskobiect sau nullScorul Kinopoisk, din 10, cu o zecimală.
metacriticobiect sau nullScorul Metacritic, din 100, ca număr întreg.
rotten_tomatoesobiect sau nullScorul Rotten Tomatoes, din 100, ca număr întreg.
tmdbobiect sau nullScorul utilizatorilor TMDB, din 10, cu până la trei zecimale.
valuenumărÎn interiorul fiecărui obiect de sursă. Scorul pe scala proprie a sursei.
votesnumăr întreg sau nullÎn interiorul fiecărui obiect de sursă. Numărul de voturi din spatele scorului sau null când nu se cunoaște.

Citește cele cinci chei de sursă după nume și sari peste orice altă cheie. Cheile de sursă vin mereu în aceeași ordine: imdb, kinopoisk, metacritic, rotten_tomatoes, tmdb.

Exemplu de răspuns

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

Doar IMDb și TMDB vin aici cu număr de voturi. Kinopoisk, Metacritic și Rotten Tomatoes au un scor și un număr de voturi null.

Obține evaluările unui serial TV

GET /3/tv/{tv_id}/ratings are aceleași chei și aceleași reguli pentru null. Transmite ID-ul serialului, de exemplu 1396 pentru Breaking Bad.

Metodă și caleÎntoarceParametri
GET /3/movie/{movie_id}/ratingsid și cinci sursemovie_id
GET /3/tv/{tv_id}/ratingsid și cinci sursetv_id
curl
curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY"

Breaking Bad nu are scor Metacritic, deci acea sursă este 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 }
}

Adaugă evaluările la un apel de detalii

append_to_response=ratings funcționează la detaliile de film și de TV. Obiectul sosește sub cheia ratings, lângă câmpurile obișnuite, fără propriul id. O pagină de listă are nevoie de o cerere pe titlu în loc de două.

CerereUnde apar scorurile
/3/movie/550?append_to_response=ratingsratings în fișa filmului
/3/tv/1396?append_to_response=credits,ratingsratings și credits în fișa serialului

Vezi detalii film și seriale TV pentru celelalte valori pe care le poți atașa.

Surse și valori null

O sursă null nu este un scor zero. Înseamnă că scorul lipsește pentru titlu.

CheieSursăScalăEticheta de afișat
imdbIMDb0 până la 10IMDb
kinopoiskKinopoisk0 până la 10Kinopoisk
metacriticMetacritic0 până la 100Metacritic
rotten_tomatoesRotten Tomatoes0 până la 100Rotten Tomatoes
tmdbTMDB0 până la 10TMDB

Acoperirea variază după titlu, deci scrie codul pentru null, nu pentru o listă fixă de surse. Oricare dintre cele cinci chei poate fi null pentru orice titlu.

Cum diferă evaluările de vote_average

Câmpurile vote_average și vote_count din fișa unui film sau serial sunt scorul utilizatorilor TMDB. Cheia tmdb poartă același scor în aceeași structură ca celelalte patru, deci un singur apel îți dă toate cele cinci surse într-un singur format.

Fiecare sursă are publicul și scala ei. Nu le face media și nu compara o valoare dintr-o sursă cu numărul de voturi din alta.

Arată evaluările într-o aplicație

Afișează doar sursele prezente. O listă scurtă de insigne ajunge pentru un card. Adaugă scala, ca un cititor să poată deosebi 8.8 din 10 de 67 din 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}`);
}

Arată eticheta la fiecare valoare. Când toate cele cinci sunt null, ascunde blocul în loc să arăți insigne goale.

Erori

Eșecurile păstrează corpul de eroare TMDB, în care success este false, iar status_code numește problema. Un titlu fără scoruri nu este una dintre ele.

HTTPstatus_codeCând
4017Cheia lipsește sau este greșită.
40236Perioada planului s-a încheiat.
40434Niciun film sau serial cu acel ID.
42925Ai depășit cererile pe minut. Așteaptă numărul de secunde din Retry-After.

Un scor necunoscut este null, nu o eroare. Detaliile sunt la erori și limite de cereri.

Note practice

  • Evaluările sunt ținute în cache la margine 6 ore, ca detaliile. O reîmprospătare mai deasă întoarce același corp.
  • O cerere cu append_to_response=ratings se numără ca o singură cerere din cele 20, 40 sau 120 pe minut.
  • Stochează scorurile împreună cu data la care le-ai preluat. Voturile cresc în timp, iar cifrele se mișcă.
  • Ca să mapezi mai întâi un ID IMDb sau Kinopoisk la un titlu, folosește căutare după ID extern. Pentru senzații în loc de scoruri, vezi atmosfere.