电影与电视剧评分

接口返回 IMDb、Kinopoisk、Metacritic、Rotten Tomatoes 和 TMDB 评分,每个来源是带 value 和 votes 的对象,未知时为 null。详情调用加 append_to_response=ratings 可合并。

更新于 以 Markdown 查看

获取电影的评分

GET /3/movie/{movie_id}/ratings 返回各评分来源为一部电影发布的分数。响应包含电影 id 和五个来源键:imdb、kinopoisk、metacritic、rotten_tomatoes 和 tmdb。每个来源键保存一个带有 value 和 votes 的对象,该来源对此作品未知时为 null。

示例加载《搏击俱乐部》(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 请求头。

响应字段

字段类型说明
idinteger电影 ID。使用 append_to_response 时不存在。
imdbobject 或 nullIMDb 评分,满分 10,保留一位小数。
kinopoiskobject 或 nullKinopoisk 评分,满分 10,保留一位小数。
metacriticobject 或 nullMetacritic 评分,满分 100,为整数。
rotten_tomatoesobject 或 nullRotten Tomatoes 评分,满分 100,为整数。
tmdbobject 或 nullTMDB 用户评分,满分 10,最多三位小数。
valuenumber在每个来源对象内。该来源自己刻度上的分数。
votesinteger 或 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。

方法和路径返回内容参数
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"

《绝命毒师》没有 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=ratings电影记录中的 ratings
/3/tv/1396?append_to_response=credits,ratings剧集记录中的 ratings 和 credits

可追加的其他取值见电影详情和电视剧。

来源与 null 值

来源为 null 不是零分。它表示该作品缺少这个评分。

键来源刻度要显示的标签
imdbIMDb0 到 10IMDb
kinopoiskKinopoisk0 到 10Kinopoisk
metacriticMetacritic0 到 100Metacritic
rotten_tomatoesRotten Tomatoes0 到 100Rotten Tomatoes
tmdbTMDB0 到 10TMDB

覆盖范围因作品而异,所以请针对 null 编写代码,而不是依赖固定的来源列表。对任何作品,五个键中的任何一个都可能为 null。

评分与 vote_average 的区别

电影或剧集记录上的 vote_average 和 vote_count 字段是 TMDB 用户评分。tmdb 键以与其他四个相同的结构携带同一个分数,所以一次调用就能以统一格式得到全部五个来源。

每个来源都有自己的受众和刻度。不要对它们取平均,也不要拿一个来源的数值去和另一个来源的投票数比较。

在应用中显示评分

只渲染存在的来源。卡片上用一个简短的徽章列表就够了。加上刻度,让读者能分清满分 10 的 8.8 和满分 100 的 67。

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 或 Kinopoisk ID 映射到作品,请用按外部 ID 查找。想了解感受而不是分数,见情绪指数。