# Jauges d'ambiance > GET /3/movie/{movie_id}/moods et GET /3/tv/{tv_id}/moods renvoient une source et une liste results. Chaque résultat a un nom d'ambiance comme fear ou humor, un avg sur une échelle de 0 à 10 et les valeurs qui le fondent. Ajoutez append_to_response=moods à un appel de détails pour fusionner les jauges sans seconde requête. ## Point de terminaison `GET /3/movie/{movie_id}/moods` ```bash curl "https://api.amodb.dev/3/movie/155/moods" \ -H "Authorization: Bearer $AMODB_KEY" ``` Réponse: ```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 ] } ] } ``` ## 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. ```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) } } ``` ### Paramètres | Paramètre | Dans | Requis | Description | | ---------- | ------- | ------------- | ------------------------------------------------------------ | | `movie_id` | chemin | oui | Identifiant numérique du film, par exemple `155`. | | `api_key` | requête | l'un des deux | Votre clé. Utilisez-la ou l'en-tête `Authorization: Bearer`. | ### Champs de la réponse | Champ | Type | Remarques | | ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `id` | entier | Identifiant du film. | | `source` | chaîne ou null | `measured` pour des données de spectateurs, `estimated` quand elles sont déduites des genres, `null` quand le titre n'a pas de données. | | `results` | tableau | Jauges d'ambiance triées par `name`. Vide quand rien n'est connu. | | `results[].name` | chaîne | Mot court en minuscules comme `fear`. | | `results[].avg` | nombre | Moyenne sur une échelle de 0 à 10. Une décimale pour les titres mesurés, un nombre entier pour les titres estimés. | | `results[].values` | tableau de nombres | Jusqu'à 24 relevés sur la même échelle de 0 à 10. Les titres mesurés vus en ont 6, les titres estimés en ont 5. | 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 ```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] } ] } ``` 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. ```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] } ] } ``` 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`. | Méthode et chemin | Renvoie | Paramètres | | ----------------------------- | ---------------------------------- | ------------------------------------------- | | `GET /movie/{movie_id}/moods` | `id`, `source` et `results` | `movie_id` | | `GET /tv/{tv_id}/moods` | `id`, `source` et `results` | `tv_id` | | `append_to_response=moods` | `source` et `results` sous `moods` | Ajouté aux détails d'un film ou d'une série | ```bash 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. | Plage | Lecture | | ------- | --------------------------------- | | 0 à 2.9 | L'ambiance est faible ou absente. | | 3 à 5.9 | L'ambiance est présente. | | 6 à 7.9 | L'ambiance est nette. | | 8 à 10 | L'ambiance définit 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. | Modèle | Règle | Remarques | | -------------- | -------------------------------------------------------------- | -------------------------------------------------------------- | | Badge | Afficher jusqu'à 3 ambiances avec `avg` à 6 ou plus | Trier d'abord par `avg`. | | Barre de jauge | Régler la largeur de la barre sur `avg` fois 10 en pourcentage | L'échelle va de 0 à 10. | | Puce de filtre | Retenir les titres dont l'ambiance choisie est à 7 ou plus | Récupérer les jauges titre par titre, puis filtrer localement. | ```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); } ``` 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. | HTTP | status_code | Quand | | ---- | ----------- | ----------------------------------------------------------------------------- | | 401 | 7 | La clé est absente ou fausse. | | 402 | 36 | La période de l'offre est terminée. | | 429 | 25 | Au-dessus de vos requêtes par minute. Attendez les secondes de `Retry-After`. | 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](https://amodb.dev/fr/errors/), et les limites sont sur [limites de débit](https://amodb.dev/fr/rate-limits/). ## 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](https://amodb.dev/fr/ratings/) pour une note et avec les [bandes originales](https://amodb.dev/fr/soundtracks/) pour la musique du même titre. ## Questions et réponses ### Que signifie une valeur d'ambiance ? Le champ avg est une intensité sur une échelle de 0 à 10, avec une décimale pour les titres mesurés. Un avg de 7 pour fear signifie que le titre fait peur, et 0 signifie que l'ambiance est absente. Ce n'est ni un pourcentage ni une note de critique. ### La liste des noms d'ambiance est-elle fixe ? Ne le supposez pas. Les noms vus aujourd'hui sont action, fear, humor, pace, profanity, romance, sadness, sex et violence, et un titre peut en avoir moins de neuf. Affichez les chaînes de noms que vous recevez pour qu'un nouveau nom apparaisse aussi. ### Que signifient measured et estimated dans source ? Measured signifie que les jauges viennent de données de spectateurs et portent des décimales. Estimated signifie qu'elles sont déduites des genres du titre : avg est alors un nombre entier. Un titre sans données a un tableau results vide et une source à null. ### Comment filtrer une liste de titres par ambiance ? Récupérez les jauges de chaque titre de votre liste, avec le point de terminaison moods ou avec append_to_response sur les détails, et gardez les titres dont l'ambiance choisie dépasse votre seuil. Le filtre s'exécute dans votre code. ### Les séries ont-elles aussi des ambiances ? Oui. Utilisez GET /3/tv/{tv_id}/moods, par exemple avec l'identifiant de série 1396. La réponse a la même forme que celle du point de terminaison des films. ## Pages liées - [API de détails de film](https://amodb.dev/fr/movies/): API de détails de film aux chemins et au JSON de TMDB v3. Obtenez un film par id, ajoutez crédits, notes et ambiances avec append_to_response, en 14 langues. - [API des séries TV](https://amodb.dev/fr/tv-series/): API de séries TV aux chemins et au JSON de TMDB v3 : une série par id avec saisons, chaînes et prochain épisode, plus classifications et plateformes. - [Notes des films et séries](https://amodb.dev/fr/ratings/): API de notes de films : scores IMDb, Kinopoisk, Metacritic, Rotten Tomatoes et TMDB d'un titre en un appel, avec null pour toute source inconnue. - [Bandes originales](https://amodb.dev/fr/soundtracks/): API de bandes originales : album et liste des morceaux d'un film ou d'une série. Appelez le point de terminaison ou ajoutez append_to_response=soundtracks. - [API Discover](https://amodb.dev/fr/discover/): API Discover avec les mêmes filtres que TMDB v3. Listez films et séries par genre, distribution, société, mot-clé, année, note, durée et plateforme. - [Démarrage rapide](https://amodb.dev/fr/quickstart/): Faites votre premier appel amodb : obtenez une clé, demandez un film en curl, JavaScript, Python, PHP ou Go, puis chargez l'affiche. En moins de 2 minutes. Mis à jour: 2026-10-18. Source: https://amodb.dev/fr/moods/