# Notes des films et séries > GET /3/movie/{movie_id}/ratings et GET /3/tv/{tv_id}/ratings renvoient les notes IMDb, Kinopoisk, Metacritic, Rotten Tomatoes et TMDB. Chaque source est un objet avec value et votes, ou null si elle est inconnue. IMDb, Kinopoisk et TMDB sont sur 10, les deux autres sur 100. Ajoutez append_to_response=ratings pour les fusionner dans les détails. ## Point de terminaison `GET /3/movie/{movie_id}/ratings` ```bash curl "https://api.amodb.dev/3/movie/550/ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` Réponse: ```json { "id": 550, "imdb": { "value": 8.8, "votes": 2669989 }, "kinopoisk": { "value": 8.7, "votes": null }, "metacritic": { "value": 67, "votes": null }, "rotten_tomatoes": { "value": 81, "votes": null }, "tmdb": { "value": 8.437, "votes": 33042 } } ``` ## Obtenir les notes d'un film `GET /3/movie/{movie_id}/ratings` renvoie les notes que publient les sources de notation pour un film. La réponse contient l'`id` du film et cinq clés de sources : `imdb`, `kinopoisk`, `metacritic`, `rotten_tomatoes` et `tmdb`. Chaque clé de source contient un objet avec `value` et `votes`, ou `null` quand cette source n'est pas connue pour le titre. L'exemple charge Fight Club (id 550) et affiche chaque source, en marquant celles qui sont inconnues. ```bash curl -sf "https://api.amodb.dev/3/movie/550/ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const res = await fetch('https://api.amodb.dev/3/movie/550/ratings', { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const ratings = await res.json(); for (const source of ['imdb', 'kinopoisk', 'metacritic', 'rotten_tomatoes', 'tmdb']) { const score = ratings[source]; console.log(source, score ? `${score.value} (votes: ${score.votes ?? 'unknown'})` : 'not known'); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/550/ratings", headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() ratings = r.json() for source in ("imdb", "kinopoisk", "metacritic", "rotten_tomatoes", "tmdb"): score = ratings[source] if score is None: print(source, "not known") else: print(source, score["value"], "votes:", score["votes"] or "unknown") ``` ```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"); } $ratings = json_decode($body, true); foreach (['imdb', 'kinopoisk', 'metacritic', 'rotten_tomatoes', 'tmdb'] as $source) { $score = $ratings[$source]; echo $source, ' ', $score === null ? 'not known' : $score['value'] . ' votes: ' . ($score['votes'] ?? 'unknown'), PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Score struct { Value float64 `json:"value"` Votes *int `json:"votes"` } type Ratings struct { IMDb *Score `json:"imdb"` Kinopoisk *Score `json:"kinopoisk"` Metacritic *Score `json:"metacritic"` RottenTomatoes *Score `json:"rotten_tomatoes"` TMDB *Score `json:"tmdb"` } func show(name string, s *Score) { if s == nil { fmt.Println(name, "not known") return } if s.Votes == nil { fmt.Println(name, s.Value, "votes: unknown") return } fmt.Println(name, s.Value, "votes:", *s.Votes) } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/ratings", 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 r Ratings if err := json.NewDecoder(res.Body).Decode(&r); err != nil { panic(err) } show("imdb", r.IMDb) show("kinopoisk", r.Kinopoisk) show("metacritic", r.Metacritic) show("rotten_tomatoes", r.RottenTomatoes) show("tmdb", r.TMDB) } ``` ### Paramètres | Paramètre | Dans | Requis | Description | | ---------- | ------- | ------------- | ------------------------------------------------------------ | | `movie_id` | chemin | oui | Identifiant numérique du film, par exemple `550`. | | `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. Absent quand vous utilisez `append_to_response`. | | `imdb` | objet ou null | Note IMDb, sur 10 avec une décimale. | | `kinopoisk` | objet ou null | Note Kinopoisk, sur 10 avec une décimale. | | `metacritic` | objet ou null | Note Metacritic, sur 100 en entier. | | `rotten_tomatoes` | objet ou null | Note Rotten Tomatoes, sur 100 en entier. | | `tmdb` | objet ou null | Note des utilisateurs TMDB, sur 10 avec jusqu'à trois décimales. | | `value` | nombre | À l'intérieur de chaque objet de source. La note sur l'échelle propre à cette source. | | `votes` | entier ou null | À l'intérieur de chaque objet de source. Nombre de votes derrière la note, ou `null` quand il n'est pas connu. | Lisez les cinq clés de sources par leur nom et ignorez toute autre clé. Les clés de sources arrivent toujours dans le même ordre : `imdb`, `kinopoisk`, `metacritic`, `rotten_tomatoes`, `tmdb`. ### Exemple de réponse ```json { "id": 550, "imdb": { "value": 8.8, "votes": 2669989 }, "kinopoisk": { "value": 8.7, "votes": null }, "metacritic": { "value": 67, "votes": null }, "rotten_tomatoes": { "value": 81, "votes": null }, "tmdb": { "value": 8.437, "votes": 33039 } } ``` Seuls IMDb et TMDB sont accompagnés d'un nombre de votes ici. Kinopoisk, Metacritic et Rotten Tomatoes ont une note et un nombre de votes `null`. ## Obtenir les notes d'une série `GET /3/tv/{tv_id}/ratings` a les mêmes clés et les mêmes règles pour null. Passez l'identifiant de la série, par exemple `1396` pour Breaking Bad. | Méthode et chemin | Renvoie | Paramètres | | --------------------------------- | -------------------- | ---------- | | `GET /3/movie/{movie_id}/ratings` | `id` et cinq sources | `movie_id` | | `GET /3/tv/{tv_id}/ratings` | `id` et cinq sources | `tv_id` | ```bash curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY" ``` Breaking Bad n'a pas de note Metacritic : cette source vaut donc `null` : ```json { "id": 1396, "imdb": { "value": 9.5, "votes": 2671962 }, "kinopoisk": { "value": 8.9, "votes": null }, "metacritic": null, "rotten_tomatoes": { "value": 96, "votes": null }, "tmdb": { "value": 9, "votes": 18863 } } ``` ## Ajouter les notes à un appel de détails `append_to_response=ratings` fonctionne sur les détails des films et des séries. L'objet arrive sous la clé `ratings` à côté des champs habituels, sans `id` propre. Une page de liste demande une requête par titre au lieu de deux. | Requête | Où apparaissent les notes | | ----------------------------------------------- | ------------------------------------------------ | | `/3/movie/550?append_to_response=ratings` | `ratings` dans la fiche du film | | `/3/tv/1396?append_to_response=credits,ratings` | `ratings` et `credits` dans la fiche de la série | Voir [détails d'un film](https://amodb.dev/fr/movies/) et [séries TV](https://amodb.dev/fr/tv-series/) pour les autres valeurs que vous pouvez ajouter. ## Sources et valeurs null Une source null n'est pas une note de zéro. Elle signifie que la note manque pour le titre. | Clé | Source | Échelle | Libellé à afficher | | ----------------- | --------------- | ------- | ------------------ | | `imdb` | IMDb | 0 à 10 | IMDb | | `kinopoisk` | Kinopoisk | 0 à 10 | Kinopoisk | | `metacritic` | Metacritic | 0 à 100 | Metacritic | | `rotten_tomatoes` | Rotten Tomatoes | 0 à 100 | Rotten Tomatoes | | `tmdb` | TMDB | 0 à 10 | TMDB | La couverture varie selon le titre : écrivez votre code pour gérer null, pas pour une liste fixe de sources. N'importe laquelle des cinq clés peut valoir null pour n'importe quel titre. ## En quoi les notes diffèrent de vote_average Les champs `vote_average` et `vote_count` d'une fiche de film ou de série sont la note des utilisateurs TMDB. La clé `tmdb` porte la même note, dans la même forme que les quatre autres : un seul appel donne donc les cinq sources dans un seul format. Chaque source a son propre public et sa propre échelle. N'en faites pas la moyenne et ne comparez pas une valeur d'une source avec le nombre de votes d'une autre. ## Afficher les notes dans une application N'affichez que les sources présentes. Une courte liste de badges suffit pour une carte. Ajoutez l'échelle pour qu'un lecteur distingue 8.8 sur 10 de 67 sur 100. ```js const labels = { imdb: ['IMDb', 10], kinopoisk: ['Kinopoisk', 10], metacritic: ['Metacritic', 100], rotten_tomatoes: ['Rotten Tomatoes', 100], tmdb: ['TMDB', 10], }; function badges(ratings) { return Object.entries(labels) .filter(([key]) => ratings[key]) .map(([key, [label, max]]) => `${label} ${ratings[key].value}/${max}`); } ``` Affichez le libellé avec chaque valeur. Quand les cinq valent null, masquez le bloc au lieu d'afficher des badges vides. ## Erreurs Les échecs gardent le corps d'erreur TMDB, où `success` vaut false et `status_code` désigne le problème. Un titre sans note n'en fait pas partie. | HTTP | status_code | Quand | | ---- | ----------- | ----------------------------------------------------------------------------- | | 401 | 7 | La clé est absente ou fausse. | | 402 | 36 | La période de l'offre est terminée. | | 404 | 34 | Aucun film ni aucune série avec cet identifiant. | | 429 | 25 | Au-dessus de vos requêtes par minute. Attendez les secondes de `Retry-After`. | Une note inconnue est `null`, pas une erreur. Les détails sont sur [erreurs](https://amodb.dev/fr/errors/) et [limites de débit](https://amodb.dev/fr/rate-limits/). ## Remarques pratiques - Les notes sont mises en cache 6 heures en périphérie, comme les détails. Les actualiser plus souvent renvoie le même corps. - Une requête avec `append_to_response=ratings` compte pour une seule requête dans vos 20, 40 ou 120 requêtes par minute. - Stockez les notes avec la date de leur récupération. Les votes augmentent avec le temps et les chiffres bougent. - Pour d'abord associer un identifiant IMDb ou Kinopoisk à un titre, utilisez la [recherche par identifiant externe](https://amodb.dev/fr/find-by-external-id/). Pour les sensations plutôt que les notes, voir [ambiances](https://amodb.dev/fr/moods/). ## Questions et réponses ### Pourquoi une source vaut-elle null ? Null signifie que la note est absente ou nulle pour ce titre. Une sortie récente ou un film régional a souvent moins de sources qu'un film célèbre : gérez donc toujours null avant de formater un nombre. Le champ votes peut aussi valoir null. ### En quoi est-ce différent de vote_average ? Le champ vote_average d'une fiche de détails est uniquement la note des utilisateurs TMDB. Le point de terminaison des notes la renvoie à nouveau sous la clé tmdb, avec trois décimales, et ajoute les quatre autres sources, chacune sous forme de value et votes. ### Puis-je faire la moyenne des cinq notes ? Non. IMDb, Kinopoisk et TMDB sont sur 10, alors que Metacritic et Rotten Tomatoes sont sur 100. Chaque source a aussi son propre public, et certaines valent null. Affichez côte à côte les sources dont vous disposez, avec leurs libellés. ### L'appel de notes coûte-t-il des requêtes supplémentaires ? C'est une requête comme les autres. Avec append_to_response=ratings, les notes arrivent dans un appel de détails : vous utilisez donc un créneau de requête par minute au lieu de deux. ## 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. - [Recherche par identifiant externe](https://amodb.dev/fr/find-by-external-id/): Retrouvez un film, une série ou une personne par id IMDb, TVDB, Wikidata ou Kinopoisk avec find de TMDB, puis lisez ids externes et faits Wikidata. - [Jauges d'ambiance](https://amodb.dev/fr/moods/): API d'ambiances avec jauges de 0 à 10 par titre. Lisez les ambiances d'un film ou d'une série, fusionnez avec append_to_response=moods, créez badges et filtres. - [Limites de débit](https://amodb.dev/fr/rate-limits/): amodb limite chaque clé en requêtes par minute sur une fenêtre glissante de 60 secondes : 20, 40 ou 120 selon l'offre. Lisez les en-têtes et gérez le 429. - [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/ratings/