Рэйтынгі фільмаў і серыялаў

GET /3/movie/{movie_id}/ratings і GET /3/tv/{tv_id}/ratings вяртаюць ацэнкі IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB. Кожная крыніца ёсць аб’ектам з value і votes або null, калі яна невядомая. IMDb, Kinopoisk і TMDB даюцца з 10, а дзве астатнія са 100. Дадайце append_to_response=ratings, каб далучыць іх да дэталяў.

Абноўлена Адкрыць у Markdown

Атрыманне рэйтынгаў фільма

GET /3/movie/{movie_id}/ratings вяртае ацэнкі, якія крыніцы рэйтынгаў публікуюць для аднаго фільма. Адказ мае id фільма і пяць ключоў крыніц: imdb, kinopoisk, metacritic, rotten_tomatoes і tmdb. Кожны ключ крыніцы змяшчае аб’ект з value і votes або null, калі гэтая крыніца для назвы невядомая.

У прыкладзе загружаецца Fight Club (id 550) і друкуецца кожная крыніца з пазнакай для невядомых.

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

Параметры

  • movie_idшляхабавязковы
    Лікавы id фільма, напрыклад 550.
  • api_keyзапытадзін з двух
    Ваш ключ. Выкарыстоўвайце яго або загаловак Authorization: Bearer.

Палі адказу

ПолеТыпЗаўвагі
idцэлы лікId фільма. Адсутнічае, калі вы выкарыстоўваеце append_to_response.
imdbаб’ект або nullАцэнка IMDb, з 10 з адным знакам пасля коскі.
kinopoiskаб’ект або nullАцэнка Kinopoisk, з 10 з адным знакам пасля коскі.
metacriticаб’ект або nullАцэнка Metacritic, са 100 у выглядзе цэлага ліку.
rotten_tomatoesаб’ект або nullАцэнка Rotten Tomatoes, са 100 у выглядзе цэлага ліку.
tmdbаб’ект або nullАцэнка карыстальнікаў TMDB, з 10 з не болей чым трыма знакамі пасля коскі.
valueлікУнутры кожнага аб’екта крыніцы. Ацэнка па ўласнай шкале гэтай крыніцы.
votesцэлы лік або nullУнутры кожнага аб’екта крыніцы. Колькасць галасоў за ацэнку або null, калі яна невядомая.

Чытайце пяць ключоў крыніц па назве і прапускайце любыя іншыя. Ключы крыніц заўсёды ідуць у адным парадку: imdb, kinopoisk, metacritic, rotten_tomatoes, tmdb.

Прыклад адказу

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

Тут колькасць галасоў ёсць толькі ў IMDb і TMDB. Kinopoisk, Metacritic і Rotten Tomatoes маюць ацэнку і колькасць галасоў null.

Атрыманне рэйтынгаў серыяла

GET /3/tv/{tv_id}/ratings мае тыя ж ключы і тыя ж правілы для null. Перадайце id серыяла, напрыклад 1396 для Breaking Bad.

Метад і шляхШто вяртаеПараметры
GET /3/movie/{movie_id}/ratingsid і пяць крыніцmovie_id
GET /3/tv/{tv_id}/ratingsid і пяць крыніцtv_id
curl
curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY"

У Breaking Bad няма ацэнкі Metacritic, таму гэтая крыніца роўная 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 }
}

Дадаванне рэйтынгаў да выкліку дэталяў

append_to_response=ratings працуе ў дэталях фільма і серыяла. Аб’ект прыходзіць пад ключом ratings побач са звычайнымі палямі, без уласнага id. Старонцы спісу патрэбны адзін запыт на назву замест двух.

ЗапытДзе з’яўляюцца ацэнкі
/3/movie/550?append_to_response=ratingsratings у запісе фільма
/3/tv/1396?append_to_response=credits,ratingsratings і credits у запісе серыяла

Іншыя значэнні, якія можна далучыць, гл. на старонках дэталі фільма і серыялы.

Крыніцы і значэнні null

Крыніца роўная null не азначае нулявую ацэнку. Гэта азначае, што ацэнкі для назвы няма.

КлючКрыніцаШкалаПодпіс для паказу
imdbIMDbад 0 да 10IMDb
kinopoiskKinopoiskад 0 да 10Kinopoisk
metacriticMetacriticад 0 да 100Metacritic
rotten_tomatoesRotten Tomatoesад 0 да 100Rotten Tomatoes
tmdbTMDBад 0 да 10TMDB

Пакрыццё залежыць ад назвы, таму арыентуйцеся на null, а не на фіксаваны спіс крыніц. Любы з пяці ключоў можа быць null для любой назвы.

Чым рэйтынгі адрозніваюцца ад vote_average

Палі vote_average і vote_count у запісе фільма або серыяла гэта ацэнка карыстальнікаў TMDB. Ключ tmdb нясе тую ж ацэнку ў той жа форме, што і чатыры іншыя, таму адзін выклік дае ўсе пяць крыніц у адным фармаце.

У кожнай крыніцы свая аўдыторыя і шкала. Не абсярэднівайце іх і не параўноўвайце значэнне адной крыніцы з колькасцю галасоў іншай.

Паказ рэйтынгаў у праграме

Адлюстроўвайце толькі наяўныя крыніцы. Для карткі хопіць кароткага спісу значкоў. Дадайце шкалу, каб чытач адрозніваў 8.8 з 10 ад 67 са 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}`);
}

Паказвайце подпіс з кожным значэннем. Калі ўсе пяць роўныя null, схавайце блок замест таго, каб паказваць пустыя значкі.

Памылкі

Збоі захоўваюць цела памылкі TMDB, дзе success роўны false, а status_code называе праблему. Назва без ацэнак да іх не адносіцца.

HTTPstatus_codeКалі
4017Ключ адсутнічае або няправільны.
40236Тэрмін дзеяння плана скончыўся.
40434Няма фільма або серыяла з гэтым id.
42925Перавышаны ліміт запытаў у хвіліну. Пачакайце Retry-After секунд.

Невядомая ацэнка гэта null, а не памылка. Падрабязнасці на старонках памылкі і ліміты запытаў.

Практычныя заўвагі

  • Рэйтынгі кэшуюцца на edge на 6 гадзін, як і дэталі. Больш частае абнаўленне вяртае тое ж цела.
  • Запыт з append_to_response=ratings лічыцца адным запытам з вашых 20, 40 або 120 запытаў у хвіліну.
  • Захоўвайце ацэнкі з датай атрымання. Галасы з часам растуць, і лічбы змяняюцца.
  • Каб спачатку супаставіць IMDb або Kinopoisk id з назвай, выкарыстоўвайце пошук па вонкавым ідэнтыфікатары. Пра пачуцці, а не ацэнкі, гл. настрой.