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

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 със заглавие, ползвайте търсене по външен идентификатор. За усещания, а не оценки, вижте настроения.