מדדי מצב רוח

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 כשהמדד נגזר מז'אנרים.

עודכן צפייה כ-Markdown

קבלת מדדי מצב רוח של סרט

GET /3/movie/{movie_id}/moods מחזיר את מדדי מצב הרוח של סרט אחד. מדד מצב רוח הוא שם וממוצע בסולם 0 עד 10. התגובה נושאת את ה-id של הסרט, source ומערך results. בכל תוצאה יש name, avg ו-values.

הדוגמה טוענת את המדדים של The Dark Knight (מזהה 155) ומדפיסה אותם מהחזק לחלש.

bashjspyphpgo
curl -sf "https://api.amodb.dev/3/movie/155/moods" \
  -H "Authorization: Bearer $AMODB_KEY"
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);
}
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
$ch = curl_init('https://api.amodb.dev/3/movie/155/moods');
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");
}
$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']);
}
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.

שדות התגובה

שדהסוגהערות
idintegerמזהה הסרט.
sourcestring או nullmeasured לנתוני צופים, estimated כשהוא נגזר מז'אנרים, null כשלכותר אין נתונים.
resultsarrayמדדי מצב רוח ממוינים לפי name. ריק כשלא ידוע דבר.
results[].namestringמילה קצרה באותיות קטנות כמו fear.
results[].avgnumberממוצע בסולם 0 עד 10. ספרה עשרונית אחת לכותרים שנמדדו, מספר שלם לכותרים משוערים.
results[].valuesarray של מספריםעד 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}/moodsid, source ו-resultsmovie_id
GET /tv/{tv_id}/moodsid, source ו-resultstv_id
append_to_response=moodssource ו-results תחת moodsמתווסף לפרטי סרט או סדרה
curl
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 ומעלהשלפו מדדים לכל כותר, ואז סננו מקומית.
JavaScript
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 משתמש.

HTTPstatus_codeמתי
4017המפתח חסר או שגוי.
40236תקופת המסלול הסתיימה.
42925מעל הבקשות שלכם לדקה. המתינו Retry-After שניות.

נקודת הקצה של moods לא עונה 404 למזהה לא מוכר. היא עונה 200 עם מערך results ריק, ו-source הוא null או חסר. כשמצרפים לפרטים, מזהה לא מוכר הוא 404 מקריאת הפרטים. הרשימה המלאה בעמוד שגיאות, והמגבלות בעמוד מגבלות קצב.

הערות מעשיות

  • כמו נתוני פרטים אחרים, מדדי מצב רוח נשמרים בקצה במטמון 6 שעות. שליפה תכופה יותר מחזירה את אותו גוף.
  • רשימה של 20 כותרים דורשת 20 בקשות מצב רוח. אם אתם כבר קוראים לפרטים לכל כותר, הוסיפו moods וחסכו את הקריאה השנייה.
  • בדקו את source לפני שמשווים בין כותרים. מדדים שנמדדו ומשוערים משתמשים באותו סולם אבל לא באותה רמת דיוק.
  • שמרו את name ואת avg יחד עם מזהה הכותר במסד הנתונים שלכם אם אתם מסננים לעיתים קרובות. סינון מקומי עדיף על בקשה לכל כותר.
  • שלבו מדדים עם דירוגים לקבלת ציון ועם פסקולים למוזיקה באותו כותר.