Měřiče nálady

GET /3/movie/{movie_id}/moods a GET /3/tv/{tv_id}/moods vracejí zdroj a seznam results. Každý výsledek má název nálady, například fear nebo humor, avg na stupnici 0 až 10 a hodnoty, ze kterých vychází. Přidejte append_to_response=moods k volání detailů a měřiče sloučíte bez druhého požadavku.

Aktualizováno Zobrazit jako Markdown

Získání měřičů nálady filmu

GET /3/movie/{movie_id}/moods vrací měřiče nálady jednoho filmu. Měřič nálady je název a průměr na stupnici 0 až 10. Odpověď nese id filmu, source a pole results. Každý výsledek obsahuje name, avg a values.

Ukázka načte měřiče pro The Dark Knight (ID 155) a vypíše je od nejsilnějšího po nejslabší.

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)
	}
}

Parametry

  • movie_idpathpovinný
    Číselné ID filmu, například 155.
  • api_keyqueryjeden ze dvou
    Váš klíč. Použijte jej, nebo hlavičku Authorization: Bearer.

Pole odpovědi

PoleTypPoznámky
idintegerID filmu.
sourcestring nebo nullmeasured pro data diváků, estimated, když je odvozeno ze žánrů, null, když titul nemá data.
resultsarrayMěřiče nálady seřazené podle name. Prázdné, když nic není známo.
results[].namestringKrátké slovo malými písmeny, například fear.
results[].avgnumberPrůměr na stupnici 0 až 10. Jedno desetinné místo u změřených titulů, celé číslo u odhadovaných.
results[].valuesarray of numbersAž 24 odečtů na stejné stupnici 0 až 10. Změřené tituly, které jsme viděli, mají 6, odhadované 5.

Dnes se vyskytují názvy action, fear, humor, pace, profanity, romance, sadness, sex a violence. Ne každý titul má všech devět, vykreslujte proto názvy z dat, ne z pevného seznamu.

Příklad odpovědi

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] }
  ]
}

Seznam je zkrácen na 3 z 9 výsledků.

Změřené a odhadované tituly

Fight Club (ID 550) zatím nemá data diváků, takže jeho měřiče jsou odvozeny ze žánrů. Každé avg je celé číslo a values má 5 položek.

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] }
  ]
}

Chcete-li s odhadovanými měřiči zacházet jinak než se změřenými, zkontrolujte source.

Získání měřičů nálady seriálu

GET /3/tv/{tv_id}/moods má stejný tvar odpovědi s ID seriálu v id. Pro Breaking Bad použijte 1396.

Metoda a cestaVracíParametry
GET /movie/{movie_id}/moodsid, source a resultsmovie_id
GET /tv/{tv_id}/moodsid, source a resultstv_id
append_to_response=moodssource a results pod moodsPřidává se k detailům filmu nebo seriálu
curl
curl -sf "https://api.amodb.dev/3/tv/1396?append_to_response=moods" -H "Authorization: Bearer $AMODB_KEY"

Když ke volání detailů přidáte moods, klíč moods leží na nejvyšší úrovni záznamu vedle title nebo name. Obsahuje source a results a nemá vlastní id. Stojí to jeden požadavek, zatímco dvě samostatná volání stojí dva.

Jak číst stupnici

Pole avg je intenzita od 0 do 10. Vyšší číslo znamená, že nálada je v titulu silnější.

RozsahVýklad
0 až 2.9Nálada je slabá nebo chybí.
3 až 5.9Nálada je přítomná.
6 až 7.9Nálada je zřetelná.
8 až 10Nálada definuje titul.

Pásma jsou návrh pro vaše rozhraní, ne pole v odpovědi. Pole values obsahuje odečty, ze kterých se průměr počítá, na stejné stupnici.

Sestavení odznaků a filtrů

Nálady zapadají do tří běžných vzorů rozhraní. Zvolte prahy, které sedí vašemu katalogu, a doladěte je.

VzorPravidloPoznámky
OdznakZobrazte až 3 nálady s avg 6 nebo vyššímNejdřív seřaďte podle avg.
Pruh měřičeŠířku pruhu nastavte na avg krát 10 jako procentoStupnice je 0 až 10.
Filtr (čip)Vyberte tituly, kde je zvolená nálada 7 nebo vyššíNačtěte měřiče pro každý titul a pak filtrujte lokálně.
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);
}

Prázdné pole results se má vykreslit jako žádné odznaky, ne jako chyba.

Chyby

Tělo chyby má success, status_code a status_message, tedy stejná pole jako TMDB.

HTTPstatus_codeKdy
4017Klíč chybí nebo je nesprávný.
40236Platnost tarifu skončila.
42925Překročen počet požadavků za minutu. Počkejte tolik sekund, kolik říká Retry-After.

Endpoint nálad neodpovídá 404 pro neznámé ID. Odpoví 200 s prázdným polem results a source je null nebo chybí. U přidání k detailům je neznámé ID 404 z volání detailů. Úplný seznam je na stránce chyby a limity na stránce limity požadavků.

Praktické poznámky

  • Jako ostatní data detailů se měřiče nálady na edge cachují 6 hodin. Častější načítání vrací stejné tělo.
  • Seznam 20 titulů potřebuje 20 požadavků na nálady. Pokud už pro každý titul voláte detaily, přidejte moods a ušetříte druhé volání.
  • Než tituly porovnáte, zkontrolujte source. Změřené a odhadované měřiče používají stejnou stupnici, ale ne stejnou přesnost.
  • Pokud filtrujete často, ukládejte name a avg spolu s ID titulu do vlastní databáze. Lokální filtr je lepší než požadavek na titul.
  • Měřiče kombinujte s hodnocením pro skóre a se soundtracky pro hudbu ve stejném titulu.