Рейтинги фільмів і серіалів

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, а не помилкою. Подробиці на сторінках помилки і ліміти запитів.

Практичні поради

  • Рейтинги кешуються на периферії мережі на 6 годин, як і деталі. Частіше оновлення повертає те саме тіло.
  • Запит із append_to_response=ratings враховується як один запит у вашому ліміті 20, 40 або 120 запитів на хвилину.
  • Зберігайте оцінки з датою отримання. Кількість голосів зростає з часом, і числа змінюються.
  • Щоб спершу зіставити IMDb id чи Kinopoisk id з фільмом, використовуйте пошук за зовнішнім ID. Для відчуттів, а не оцінок, дивіться настрої.