Індыкатары настрою

Атрыманне індыкатараў настрою фільма

GET /3/movie/{movie_id}/moods вяртае індыкатары настрою аднаго фільма. Індыкатар настрою складаецца з назвы і сярэдняга значэння па шкале ад 0 да 10. Адказ утрымлівае id фільма, source і масіў results. Кожны вынік мае name, avg і values.

У прыкладзе загружаюцца індыкатары фільма The Dark Knight (id 155) і друкуюцца ад найсільнейшага да найслабейшага.

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шляхабавязковы
  Лікавы id фільма, напрыклад 155.
• api_keyзапытадзін з двух
  Ваш ключ. Выкарыстоўвайце яго або загаловак Authorization: Bearer.

Палі адказу

Сёння сустракаюцца назвы action, fear, humor, pace, profanity, romance, sadness, sex і violence. Не ў кожнай назвы ёсць усе дзевяць, таму адлюстроўвайце назвы з даных, а не з фіксаванага спісу.

Прыклад адказу

{
  "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 (id 550) пакуль не мае даных гледачоў, таму яго індыкатары вылічаны па жанрах. Кожнае avg з’яўляецца цэлым лікам, а values мае 5 запісаў.

{
  "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 серыяла ў id. Для Breaking Bad выкарыстоўвайце 1396.

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. Чым вышэй лік, тым мацнейшы настрой у назве.

Гэтыя дыяпазоны служаць прапановай для вашага інтэрфейсу, а не полем у адказе. Масіў values змяшчае значэнні, з якіх складзена сярэдняе, на той жа шкале.

Значкі і фільтры

Настроі добра пасуюць да трох распаўсюджаных шаблонаў інтэрфейсу. Падбярыце парогі пад свой каталог і наладзьце іх.

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.

Эндпоінт moods не адказвае 404 на невядомы id. Ён адказвае 200 з пустым масівам results, а source роўны null або адсутнічае. Пры дадаванні да дэталяў невядомы id дае 404 ад выкліку дэталяў. Поўны спіс ёсць на старонцы памылкі, а ліміты на старонцы ліміты запытаў.

Практычныя заўвагі

• Як і іншыя даныя дэталяў, індыкатары настрою кэшуюцца на edge на 6 гадзін. Больш частыя запыты вяртаюць тое ж цела.
• Для спісу з 20 назваў патрэбна 20 запытаў настрою. Калі вы ўжо выклікаеце дэталі для кожнай назвы, дадайце moods і зэканомце другі выклік.
• Правярайце source, перш чым параўноўваць назвы. Вымераныя і ацэначныя індыкатары выкарыстоўваюць адну шкалу, але не аднолькавую дакладнасць.
• Калі вы часта фільтруеце, захоўвайце name і avg разам з id назвы ў сваёй базе даных. Лакальны фільтр лепшы за запыт на кожную назву.
• Спалучайце індыкатары з рэйтынгамі для ацэнкі і з саўндтрэкамі для музыкі той жа назвы.