Jauges d'ambiance

Obtenir les jauges d'ambiance d'un film

GET /3/movie/{movie_id}/moods renvoie les jauges d'ambiance d'un film. Une jauge d'ambiance est un nom et une moyenne sur une échelle de 0 à 10. La réponse contient l'id du film, une source et un tableau results. Chaque résultat contient name, avg et values.

L'exemple charge les jauges de The Dark Knight (id 155) et les affiche de la plus forte à la plus faible.

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

Paramètres

• movie_idcheminobligatoire
  Identifiant numérique du film, par exemple 155.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.

Champs de la réponse

Les noms vus aujourd'hui sont action, fear, humor, pace, profanity, romance, sadness, sex et violence. Tous les titres n'ont pas les neuf : affichez donc les noms issus des données et non d'une liste fixe.

Exemple de réponse

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

La liste est réduite à 3 des 9 résultats.

Titres mesurés et estimés

Fight Club (id 550) n'a pas encore de données de spectateurs : ses jauges sont donc déduites de ses genres. Chaque avg est un nombre entier et values a 5 entrées.

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

Vérifiez source si vous voulez traiter les jauges estimées autrement que les jauges mesurées.

Obtenir les jauges d'ambiance d'une série

GET /3/tv/{tv_id}/moods a la même forme de réponse, avec l'identifiant de la série dans id. Pour Breaking Bad, utilisez 1396.

curl -sf "https://api.amodb.dev/3/tv/1396?append_to_response=moods" -H "Authorization: Bearer $AMODB_KEY"

Quand vous ajoutez moods à un appel de détails, la clé moods se trouve au niveau supérieur de la fiche, à côté de title ou name. Elle contient source et results et n'a pas d'id propre. Cela coûte une requête, alors que deux appels séparés en coûtent deux.

Comment lire l'échelle

Le champ avg est une intensité de 0 à 10. Un nombre plus élevé signifie que l'ambiance est plus forte dans le titre.

Ces tranches sont une suggestion pour votre interface, pas un champ de la réponse. Le tableau values contient les relevés derrière la moyenne, sur la même échelle.

Construire des badges et des filtres

Les ambiances conviennent à trois modèles d'interface courants. Choisissez des seuils adaptés à votre catalogue et ajustez-les.

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

Un tableau results vide doit s'afficher comme l'absence de badges, pas comme une erreur.

Erreurs

Le corps d'erreur a success, status_code et status_message, les mêmes champs que TMDB.

Le point de terminaison des ambiances ne répond pas 404 pour un identifiant inconnu. Il répond 200 avec un tableau results vide, et source vaut null ou manque. Ajouté aux détails, un identifiant inconnu donne un 404 de l'appel de détails. La liste complète est sur erreurs, et les limites sont sur limites de débit.

Remarques pratiques

• Comme les autres données de détails, les jauges d'ambiance sont mises en cache 6 heures en périphérie. Les demander plus souvent renvoie le même corps.
• Une liste de 20 titres demande 20 requêtes d'ambiances. Si vous appelez déjà les détails de chaque titre, ajoutez moods et économisez le second appel.
• Vérifiez source avant de comparer des titres. Les jauges mesurées et estimées utilisent la même échelle mais pas la même précision.
• Stockez name et avg avec l'identifiant du titre dans votre propre base de données si vous filtrez souvent. Un filtre local vaut mieux qu'une requête par titre.
• Combinez les jauges avec les notes pour une note et avec les bandes originales pour la musique du même titre.