# דירוגי סרטים וסדרות > 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 /3/movie/{movie_id}/ratings` ```bash curl "https://api.amodb.dev/3/movie/550/ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` תגובה: ```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": 33042 } } ``` ## קבלת דירוגים של סרט `GET /3/movie/{movie_id}/ratings` מחזיר את הציונים שמקורות דירוג מפרסמים לסרט אחד. בתגובה יש את ה-`id` של הסרט וחמישה מפתחות מקור: `imdb`, `kinopoisk`, `metacritic`, `rotten_tomatoes` ו-`tmdb`. כל מפתח מקור מחזיק אובייקט עם `value` ו-`votes`, או `null` כשהמקור הזה אינו ידוע לכותר. הדוגמה טוענת את Fight Club (מזהה 550) ומדפיסה כל מקור, ומסמנת את אלה שאינם ידועים. ```bash curl -sf "https://api.amodb.dev/3/movie/550/ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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'); } ``` ```python 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 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; } ``` ```go 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`. ### תגובה לדוגמה ```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}/ratings` | `id` וחמישה מקורות | `movie_id` | | `GET /3/tv/{tv_id}/ratings` | `id` וחמישה מקורות | `tv_id` | ```bash 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=ratings` | `ratings` ברשומת הסרט | | `/3/tv/1396?append_to_response=credits,ratings` | `ratings` ו-`credits` ברשומת הסדרה | ראו [פרטי סרט](https://amodb.dev/he/movies/) ו[סדרות טלוויזיה](https://amodb.dev/he/tv-series/) לשאר הערכים שאפשר לצרף. ## מקורות וערכי 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. ```js 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`, לא שגיאה. פרטים בעמודים [שגיאות](https://amodb.dev/he/errors/) ו[מגבלות קצב](https://amodb.dev/he/rate-limits/). ## הערות מעשיות - דירוגים נשמרים בקצה במטמון 6 שעות, כמו פרטים. רענון תכוף יותר מחזיר את אותו גוף. - בקשה עם `append_to_response=ratings` נספרת כבקשה אחת מתוך 20, 40 או 120 הבקשות שלכם לדקה. - שמרו ציונים יחד עם התאריך שבו שלפתם אותם. הצבעות גדלות עם הזמן והמספרים זזים. - כדי למפות קודם מזהה IMDb או Kinopoisk לכותר, השתמשו בעמוד [חיפוש לפי מזהה חיצוני](https://amodb.dev/he/find-by-external-id/). לתחושות במקום ציונים ראו [מדדי מצב רוח](https://amodb.dev/he/moods/). ## שאלות ותשובות ### למה מקור הוא null? null אומר שהציון חסר או אפס עבור הכותר הזה. יציאה חדשה או סרט אזורי מגיעים לעיתים קרובות עם פחות מקורות מכותר מפורסם, ולכן תמיד טפלו ב-null לפני שמעצבים מספר. גם השדה votes יכול להיות null. ### במה זה שונה מ-vote_average? השדה vote_average ברשומת פרטים הוא ציון המשתמשים של TMDB בלבד. נקודת הקצה של הדירוגים מחזירה אותו שוב תחת המפתח tmdb, עם שלוש ספרות עשרוניות, ומוסיפה את ארבעת המקורות האחרים, כל אחד עם value ו-votes. ### אפשר לחשב ממוצע של חמשת הציונים? אל תעשו זאת. IMDb, Kinopoisk ו-TMDB מתוך 10, בעוד Metacritic ו-Rotten Tomatoes מתוך 100. לכל מקור יש גם קהל משלו, וחלקם null. הציגו זה לצד זה את המקורות שיש לכם, עם התוויות שלהם. ### האם קריאת הדירוגים עולה בקשות נוספות? היא בקשה אחת כמו כל קריאה אחרת. עם append_to_response=ratings הציונים מגיעים בתוך קריאת פרטים, ולכן אתם צורכים מקום אחד בדקה במקום שניים. ## עמודים קשורים - [API פרטי סרט](https://amodb.dev/he/movies/): API פרטי סרט עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סרט לפי מזהה, הוסיפו קרדיטים, דירוגים, מצבי רוח ופסקולים עם append_to_response, ב-14 שפות. - [API סדרות טלוויזיה](https://amodb.dev/he/tv-series/): API סדרות טלוויזיה עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סדרה לפי מזהה ב-GET /3/tv/{series_id} עם עונות, רשתות והפרק הבא, וגם סיווגי גיל וספקי צפייה. - [חיפוש לפי מזהה חיצוני](https://amodb.dev/he/find-by-external-id/): חפשו סרט, סדרה או אדם לפי מזהה IMDb, TVDB, Wikidata או Kinopoisk עם נקודת הקצה find של TMDB v3, וקראו מזהים חיצוניים ועובדות Wikidata על כל כותר. - [מדדי מצב רוח](https://amodb.dev/he/moods/): API מצב רוח בסרטים עם מדדים בסולם 0 עד 10 לכל כותר. קראו מצבי רוח של סרט או סדרה, מזגו אותם עם append_to_response=moods ובנו תגים או מסננים. - [מגבלות קצב](https://amodb.dev/he/rate-limits/): amodb מגביל כל מפתח לפי בקשות לדקה בחלון נע של 60 שניות: 20, 40 או 120 בהתאם למסלול שלכם. קראו את כותרות מגבלת הקצב וטפלו ב-429 עם Retry-After. - [מדריך למתחילים](https://amodb.dev/he/quickstart/): בצעו את הקריאה הראשונה ל-amodb: קבלו מפתח, בקשו פרטי סרט ב-curl, JavaScript, Python, PHP או Go, ואז טענו את הפוסטר מ-img.amodb.dev. פחות מ-2 דקות. עודכן: 2026-10-18. Source: https://amodb.dev/he/ratings/