# מדדי מצב רוח > GET /3/movie/{movie_id}/moods ו-GET /3/tv/{tv_id}/moods מחזירים source ורשימת results. בכל תוצאה יש שם מצב רוח כמו fear או humor, ערך avg בסולם 0 עד 10 והערכים שמאחוריו. הוסיפו append_to_response=moods לקריאת פרטים כדי למזג את המדדים בלי בקשה שנייה. הערך source הוא measured לנתוני צופים או estimated כשהמדד נגזר מז'אנרים. ## נקודת קצה `GET /3/movie/{movie_id}/moods` ```bash curl "https://api.amodb.dev/3/movie/155/moods" \ -H "Authorization: Bearer $AMODB_KEY" ``` תגובה: ```json { "id": 155, "source": "measured", "results": [ { "name": "action", "avg": 3.9, "values": [ 3.6, 3.4, 4.2 ] }, { "name": "fear", "avg": 5.2, "values": [ 3.6, 6, 4.8 ] }, { "name": "humor", "avg": 0.9, "values": [ 2.4, 1.8, 0.4 ] } ] } ``` ## קבלת מדדי מצב רוח של סרט `GET /3/movie/{movie_id}/moods` מחזיר את מדדי מצב הרוח של סרט אחד. מדד מצב רוח הוא שם וממוצע בסולם 0 עד 10. התגובה נושאת את ה-`id` של הסרט, `source` ומערך `results`. בכל תוצאה יש `name`, `avg` ו-`values`. הדוגמה טוענת את המדדים של The Dark Knight (מזהה 155) ומדפיסה אותם מהחזק לחלש. ```bash curl -sf "https://api.amodb.dev/3/movie/155/moods" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const res = await fetch('https://api.amodb.dev/3/movie/155/moods', { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { source, results } = await res.json(); console.log('source:', source); for (const m of [...results].sort((a, b) => b.avg - a.avg)) { console.log(m.name.padEnd(10), m.avg); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/155/moods", headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() data = r.json() print("source:", data.get("source")) for m in sorted(data["results"], key=lambda m: m["avg"], reverse=True): print(f"{m['name']:<10} {m['avg']}") ``` ```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"); } $data = json_decode($body, true); echo 'source: ', $data['source'] ?? 'none', PHP_EOL; $results = $data['results']; usort($results, fn ($a, $b) => $b['avg'] <=> $a['avg']); foreach ($results as $m) { printf("%-10s %.1f\n", $m['name'], $m['avg']); } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "sort" "time" ) type Mood struct { Name string `json:"name"` Avg float64 `json:"avg"` Values []float64 `json:"values"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/155/moods", 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 body struct { Source string `json:"source"` Results []Mood `json:"results"` } if err := json.NewDecoder(res.Body).Decode(&body); err != nil { panic(err) } fmt.Println("source:", body.Source) sort.Slice(body.Results, func(i, j int) bool { return body.Results[i].Avg > body.Results[j].Avg }) for _, m := range body.Results { fmt.Printf("%-10s %.1f\n", m.Name, m.Avg) } } ``` ### פרמטרים | פרמטר | מיקום | חובה | תיאור | | ---------- | ------ | ---------- | -------------------------------------------------------- | | `movie_id` | נתיב | כן | מזהה סרט מספרי, למשל `155`. | | `api_key` | שאילתה | אחד משניים | המפתח שלכם. השתמשו בו או בכותרת `Authorization: Bearer`. | ### שדות התגובה | שדה | סוג | הערות | | ------------------ | --------------- | ------------------------------------------------------------------------------------ | | `id` | integer | מזהה הסרט. | | `source` | string או null | `measured` לנתוני צופים, `estimated` כשהוא נגזר מז'אנרים, `null` כשלכותר אין נתונים. | | `results` | array | מדדי מצב רוח ממוינים לפי `name`. ריק כשלא ידוע דבר. | | `results[].name` | string | מילה קצרה באותיות קטנות כמו `fear`. | | `results[].avg` | number | ממוצע בסולם 0 עד 10. ספרה עשרונית אחת לכותרים שנמדדו, מספר שלם לכותרים משוערים. | | `results[].values` | array של מספרים | עד 24 קריאות באותו סולם 0 עד 10. לכותרים שנמדדו שנראו יש 6, ולכותרים משוערים יש 5. | השמות שנראו כיום הם `action`, `fear`, `humor`, `pace`, `profanity`, `romance`, `sadness`, `sex` ו-`violence`. לא לכל כותר יש את כל התשעה, ולכן הציגו שמות מתוך הנתונים ולא מרשימה קבועה. ### תגובה לדוגמה ```json { "id": 155, "source": "measured", "results": [ { "name": "action", "avg": 3.9, "values": [3.6, 3.4, 4.2, 4.2, 4.8, 3] }, { "name": "fear", "avg": 5.2, "values": [3.6, 6, 4.8, 6.4, 6.4, 3.8] }, { "name": "humor", "avg": 0.9, "values": [2.4, 1.8, 0.4, 0.4, 0, 0.5] } ] } ``` הרשימה קוצרה ל-3 מתוך 9 התוצאות. ### כותרים שנמדדו וכותרים משוערים ל-Fight Club (מזהה 550) אין עדיין נתוני צופים, ולכן המדדים שלו נגזרים מהז'אנרים. כל `avg` הוא מספר שלם ובמערך `values` יש 5 פריטים. ```json { "id": 550, "source": "estimated", "results": [ { "name": "action", "avg": 4, "values": [3, 4, 5, 4, 3] }, { "name": "fear", "avg": 7, "values": [6, 7, 8, 7, 6] } ] } ``` בדקו את `source` אם אתם רוצים להתייחס למדדים משוערים אחרת ממדדים שנמדדו. ## קבלת מדדי מצב רוח של סדרה ל-`GET /3/tv/{tv_id}/moods` אותו מבנה תגובה, עם מזהה הסדרה ב-`id`. עבור Breaking Bad השתמשו ב-`1396`. | שיטה ונתיב | מה מוחזר | פרמטרים | | ----------------------------- | -------------------------------- | ------------------------ | | `GET /movie/{movie_id}/moods` | `id`, `source` ו-`results` | `movie_id` | | `GET /tv/{tv_id}/moods` | `id`, `source` ו-`results` | `tv_id` | | `append_to_response=moods` | `source` ו-`results` תחת `moods` | מתווסף לפרטי סרט או סדרה | ```bash curl -sf "https://api.amodb.dev/3/tv/1396?append_to_response=moods" -H "Authorization: Bearer $AMODB_KEY" ``` כשמוסיפים `moods` לקריאת פרטים, המפתח `moods` נמצא ברמה העליונה של הרשומה ליד `title` או `name`. הוא מחזיק `source` ו-`results` ואין לו `id` משלו. זה עולה בקשה אחת, בעוד ששתי קריאות נפרדות עולות שתיים. ## איך לקרוא את הסולם השדה `avg` הוא עוצמה מ-0 עד 10. מספר גבוה יותר אומר שמצב הרוח חזק יותר בכותר. | טווח | קריאה | | -------- | ------------------------ | | 0 עד 2.9 | מצב הרוח חלש או נעדר. | | 3 עד 5.9 | מצב הרוח קיים. | | 6 עד 7.9 | מצב הרוח ברור. | | 8 עד 10 | מצב הרוח מגדיר את הכותר. | הטווחים הם הצעה לממשק שלכם, לא שדה בתגובה. המערך `values` מחזיק את הקריאות שמאחורי הממוצע, באותו סולם. ## בניית תגים ומסננים מצבי רוח מתאימים לשלושה דפוסי ממשק נפוצים. בחרו ספים שמתאימים לקטלוג שלכם וכווננו אותם. | דפוס | כלל | הערות | | ---------- | --------------------------------------------- | ------------------------------------- | | תג | להציג עד 3 מצבי רוח עם `avg` של 6 ומעלה | מיינו קודם לפי `avg`. | | סרגל מדד | לקבוע את רוחב הסרגל כ-`avg` כפול 10 באחוזים | הסולם הוא 0 עד 10. | | צ'יפ סינון | להתאים כותרים שבהם מצב הרוח שנבחר הוא 7 ומעלה | שלפו מדדים לכל כותר, ואז סננו מקומית. | ```js function topMoods(results, min = 6, limit = 3) { return results .filter((m) => m.avg >= min) .sort((a, b) => b.avg - a.avg) .slice(0, limit) .map((m) => m.name); } function matchesMood(results, name, min = 7) { return results.some((m) => m.name === name && m.avg >= min); } ``` מערך `results` ריק צריך להיות מוצג כאין תגים, לא כשגיאה. ## שגיאות גוף השגיאה כולל `success`, `status_code` ו-`status_message`, אותם שדות שבהם TMDB משתמש. | HTTP | status_code | מתי | | ---- | ----------- | ------------------------------------------------- | | 401 | 7 | המפתח חסר או שגוי. | | 402 | 36 | תקופת המסלול הסתיימה. | | 429 | 25 | מעל הבקשות שלכם לדקה. המתינו `Retry-After` שניות. | נקודת הקצה של moods לא עונה 404 למזהה לא מוכר. היא עונה 200 עם מערך `results` ריק, ו-`source` הוא `null` או חסר. כשמצרפים לפרטים, מזהה לא מוכר הוא 404 מקריאת הפרטים. הרשימה המלאה בעמוד [שגיאות](https://amodb.dev/he/errors/), והמגבלות בעמוד [מגבלות קצב](https://amodb.dev/he/rate-limits/). ## הערות מעשיות - כמו נתוני פרטים אחרים, מדדי מצב רוח נשמרים בקצה במטמון 6 שעות. שליפה תכופה יותר מחזירה את אותו גוף. - רשימה של 20 כותרים דורשת 20 בקשות מצב רוח. אם אתם כבר קוראים לפרטים לכל כותר, הוסיפו `moods` וחסכו את הקריאה השנייה. - בדקו את `source` לפני שמשווים בין כותרים. מדדים שנמדדו ומשוערים משתמשים באותו סולם אבל לא באותה רמת דיוק. - שמרו את `name` ואת `avg` יחד עם מזהה הכותר במסד הנתונים שלכם אם אתם מסננים לעיתים קרובות. סינון מקומי עדיף על בקשה לכל כותר. - שלבו מדדים עם [דירוגים](https://amodb.dev/he/ratings/) לקבלת ציון ועם [פסקולים](https://amodb.dev/he/soundtracks/) למוזיקה באותו כותר. ## שאלות ותשובות ### מה משמעות ערך של מצב רוח? השדה avg הוא עוצמה בסולם 0 עד 10, עם ספרה עשרונית אחת לכותרים שנמדדו. avg של 7 עבור fear אומר שהכותר מפחיד, ו-0 אומר שמצב הרוח נעדר. זה לא אחוז וגם לא ציון ביקורת. ### האם רשימת שמות מצבי הרוח קבועה? אל תניחו שכן. השמות שנראו כיום הם action, fear, humor, pace, profanity, romance, sadness, sex ו-violence, ולכותר יכולים להיות פחות מתשעה. הציגו את מחרוזות השמות שאתם מקבלים כדי ששם חדש עדיין יופיע. ### מה פירוש measured ו-estimated ב-source? measured אומר שהמדדים מגיעים מנתוני צופים ונושאים ספרות עשרוניות. estimated אומר שהם נגזרים מהז'אנרים של הכותר, ולכן avg הוא מספר שלם. לכותר בלי נתונים יש מערך results ריק ו-source שהוא null. ### איך מסננים רשימת כותרים לפי מצב רוח? שלפו את המדדים לכל כותר ברשימה שלכם, בנקודת הקצה של moods או עם append_to_response על פרטים, והשאירו את הכותרים שמצב הרוח שבחרתם עובר אצלהם את הסף שלכם. הסינון רץ בקוד שלכם. ### האם גם לסדרות יש מצבי רוח? כן. השתמשו ב-GET /3/tv/{tv_id}/moods, למשל עם מזהה סדרה 1396. לתגובה אותו מבנה כמו בנקודת הקצה של סרטים. ## עמודים קשורים - [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/ratings/): API דירוגי סרטים וסדרות שמחזיר ציוני IMDb, Kinopoisk, Metacritic, Rotten Tomatoes ו-TMDB לכותר בקריאה אחת, עם value ו-votes ו-null לכל מקור שאינו ידוע. - [פסקולים](https://amodb.dev/he/soundtracks/): API פסקולים שמחזיר את אלבום הפסקול של סרט או סדרה עם רשימת הרצועות שלו. קראו ל-GET /3/movie/{movie_id}/soundtracks או הוסיפו append_to_response=soundtracks. - [API גילוי](https://amodb.dev/he/discover/): Discover API עם אותם מסננים כמו TMDB v3. הציגו סרטים וסדרות לפי ז'אנר, שחקנים, חברה, מילת מפתח, שנה, דירוג, משך וספק סטרימינג, עם מיון ודפדוף בתוצאות. - [מדריך למתחילים](https://amodb.dev/he/quickstart/): בצעו את הקריאה הראשונה ל-amodb: קבלו מפתח, בקשו פרטי סרט ב-curl, JavaScript, Python, PHP או Go, ואז טענו את הפוסטר מ-img.amodb.dev. פחות מ-2 דקות. עודכן: 2026-10-18. Source: https://amodb.dev/he/moods/