דירוגי סרטים וסדרות
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 כדי למזג אותו לפרטים. כל חמשת המקורות מגיעים לכותר בקריאה אחת.
קבלת דירוגים של סרט
GET / מחזיר את הציונים שמקורות דירוג מפרסמים לסרט אחד. בתגובה יש את ה-id של הסרט וחמישה מפתחות מקור: imdb, kinopoisk, metacritic, rotten_tomatoes ו-tmdb. כל מפתח מקור מחזיק אובייקט עם value ו-votes, או null כשהמקור הזה אינו ידוע לכותר.
הדוגמה טוענת את Fight Club (מזהה 550) ומדפיסה כל מקור, ומסמנת את אלה שאינם ידועים.
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.
שדות התגובה
| שדה | סוג | הערות |
|---|---|---|
id | integer | מזהה הסרט. לא קיים כשמשתמשים ב-append_to_response. |
imdb | object או null | ציון IMDb, מתוך 10 עם ספרה עשרונית אחת. |
kinopoisk | object או null | ציון Kinopoisk, מתוך 10 עם ספרה עשרונית אחת. |
metacritic | object או null | ציון Metacritic, מתוך 100 כמספר שלם. |
rotten_tomatoes | object או null | ציון Rotten Tomatoes, מתוך 100 כמספר שלם. |
tmdb | object או null | ציון המשתמשים של TMDB, מתוך 10 עם עד שלוש ספרות עשרוניות. |
value | number | בתוך כל אובייקט מקור. הציון בסולם של אותו מקור. |
votes | integer או null | בתוך כל אובייקט מקור. מספר ההצבעות שמאחורי הציון, או null כשאינו ידוע. |
קראו את חמשת מפתחות המקור לפי שם ודלגו על כל מפתח אחר. מפתחות המקור תמיד מגיעים באותו סדר: imdb, kinopoisk, metacritic, rotten_tomatoes, tmdb.
תגובה לדוגמה
{
"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 / אותם מפתחות ואותם כללי null. העבירו את מזהה הסדרה, למשל 1396 עבור Breaking Bad.
| שיטה ונתיב | מה מוחזר | פרמטרים |
|---|---|---|
GET / | id וחמישה מקורות | movie_id |
GET / | id וחמישה מקורות | tv_id |
curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY"ל-Breaking Bad אין ציון Metacritic, ולכן המקור הזה הוא null:
{
"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_ עובד בפרטי סרט ובפרטי סדרה. האובייקט מגיע תחת המפתח ratings ליד השדות הרגילים, בלי id משלו. עמוד רשימה צריך בקשה אחת לכותר במקום שתיים.
| בקשה | איפה הציונים מופיעים |
|---|---|
/ | ratings ברשומת הסרט |
/ | ratings ו-credits ברשומת הסדרה |
ראו פרטי סרט וסדרות טלוויזיה לשאר הערכים שאפשר לצרף.
מקורות וערכי null
מקור null אינו ציון אפס. הוא אומר שהציון חסר לכותר.
| מפתח | מקור | סולם | תווית להצגה |
|---|---|---|---|
imdb | IMDb | 0 עד 10 | IMDb |
kinopoisk | Kinopoisk | 0 עד 10 | Kinopoisk |
metacritic | Metacritic | 0 עד 100 | Metacritic |
rotten_tomatoes | Rotten Tomatoes | 0 עד 100 | Rotten Tomatoes |
tmdb | TMDB | 0 עד 10 | TMDB |
הכיסוי משתנה לפי כותר, ולכן כתבו קוד שמתמודד עם null ולא עם רשימה קבועה של מקורות. כל אחד מחמשת המפתחות יכול להיות null בכל כותר.
במה דירוגים שונים מ-vote_average
השדות vote_average ו-vote_count ברשומת סרט או סדרה הם ציון המשתמשים של TMDB. המפתח tmdb נושא את אותו ציון באותו מבנה כמו ארבעת האחרים, ולכן קריאה אחת נותנת את חמשת המקורות בפורמט אחד.
לכל מקור יש קהל וסולם משלו. אל תחשבו ביניהם ממוצע ואל תשוו ערך של מקור אחד למספר ההצבעות של אחר.
הצגת דירוגים באפליקציה
הציגו רק את המקורות שקיימים. רשימת תגים קצרה מספיקה לכרטיס. הוסיפו את הסולם כדי שקורא יוכל להבדיל בין 8.8 מתוך 10 ל-67 מתוך 100.
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 מציין את הבעיה. כותר בלי ציונים אינו אחד מהם.
| HTTP | status_code | מתי |
|---|---|---|
| 401 | 7 | המפתח חסר או שגוי. |
| 402 | 36 | תקופת המסלול הסתיימה. |
| 404 | 34 | אין סרט או סדרה עם המזהה הזה. |
| 429 | 25 | מעל הבקשות שלכם לדקה. המתינו Retry-After שניות. |
ציון לא ידוע הוא null, לא שגיאה. פרטים בעמודים שגיאות ומגבלות קצב.
הערות מעשיות
- דירוגים נשמרים בקצה במטמון 6 שעות, כמו פרטים. רענון תכוף יותר מחזיר את אותו גוף.
- בקשה עם
append_נספרת כבקשה אחת מתוך 20, 40 או 120 הבקשות שלכם לדקה.to_ response= ratings - שמרו ציונים יחד עם התאריך שבו שלפתם אותם. הצבעות גדלות עם הזמן והמספרים זזים.
- כדי למפות קודם מזהה IMDb או Kinopoisk לכותר, השתמשו בעמוד חיפוש לפי מזהה חיצוני. לתחושות במקום ציונים ראו מדדי מצב רוח.