דירוגי סרטים וסדרות

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 (מזהה 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נתיבחובה
    מזהה סרט מספרי, למשל 550.
  • api_keyשאילתהאחד משניים
    המפתח שלכם. השתמשו בו או בכותרת Authorization: Bearer.

שדות התגובה

שדהסוגהערות
idintegerמזהה הסרט. לא קיים כשמשתמשים ב-append_to_response.
imdbobject או nullציון IMDb, מתוך 10 עם ספרה עשרונית אחת.
kinopoiskobject או nullציון Kinopoisk, מתוך 10 עם ספרה עשרונית אחת.
metacriticobject או nullציון Metacritic, מתוך 100 כמספר שלם.
rotten_tomatoesobject או nullציון Rotten Tomatoes, מתוך 100 כמספר שלם.
tmdbobject או nullציון המשתמשים של TMDB, מתוך 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. העבירו את מזהה הסדרה, למשל 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 אינו ציון אפס. הוא אומר שהציון חסר לכותר.

מפתחמקורסולםתווית להצגה
imdbIMDb0 עד 10IMDb
kinopoiskKinopoisk0 עד 10Kinopoisk
metacriticMetacritic0 עד 100Metacritic
rotten_tomatoesRotten Tomatoes0 עד 100Rotten Tomatoes
tmdbTMDB0 עד 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אין סרט או סדרה עם המזהה הזה.
42925מעל הבקשות שלכם לדקה. המתינו Retry-After שניות.

ציון לא ידוע הוא null, לא שגיאה. פרטים בעמודים שגיאות ומגבלות קצב.

הערות מעשיות

  • דירוגים נשמרים בקצה במטמון 6 שעות, כמו פרטים. רענון תכוף יותר מחזיר את אותו גוף.
  • בקשה עם append_to_response=ratings נספרת כבקשה אחת מתוך 20, 40 או 120 הבקשות שלכם לדקה.
  • שמרו ציונים יחד עם התאריך שבו שלפתם אותם. הצבעות גדלות עם הזמן והמספרים זזים.
  • כדי למפות קודם מזהה IMDb או Kinopoisk לכותר, השתמשו בעמוד חיפוש לפי מזהה חיצוני. לתחושות במקום ציונים ראו מדדי מצב רוח.